# KanbanGit Domain Model

## Purpose

This document defines the canonical domain concepts, relationships, and invariants for KanbanGit. It is intended to guide future Laravel models, migrations, policies, services, frontend types, and UI behavior.

## Core entities

### User

Represents an authenticated person inside the application.

Responsibilities:

- Owns direct project permissions
- May belong to one or more teams
- May appear in user-type ticket fields
- Appears as the actor for worklog entries
- May hold application-wide admin access

### Team

Represents a named group of users.

Responsibilities:

- Groups users for permission assignment
- Carries project permissions that are inherited by its members

### Permission

Represents an action grant.

Permission scopes:

- Global admin access for application-wide administration
- Project-scoped `create`
- Project-scoped `view`
- Project-scoped `edit`
- Project-scoped `delete`

Assignment rules:

- Permissions may be assigned directly to a user
- Permissions may be assigned to a team
- A user's effective permissions are the union of direct permissions and team-inherited permissions

### Project

Represents the primary organizational boundary for workflow configuration and tickets.

Required properties:

- Name
- Project key

Owns:

- Board columns
- Ticket type definitions
- Ticket priority definitions
- Ticket field definitions
- Ticket link type definitions
- Tickets
- Repository connections

### BoardColumn

Represents one configurable column on a project's board.

Required properties:

- Project
- Label
- Position

Behavior:

- Defines a valid board status
- Controls board ordering through its position

### Ticket

Represents a project work item.

Required properties:

- Project
- Ticket key
- Sequence index
- Title
- Description
- Acceptance criteria
- Status context
- Type
- Priority

Optional properties:

- Parent ticket
- Block comment

Associated concepts:

- Custom field values based on project field definitions
- Ticket links
- Worklog entries
- Future branch references
- Future pull request references

### TicketType

Represents a project-specific ticket type label.

Required properties:

- Project
- Label
- System key
- Is built-in

Rules:

- Every project has built-in `Task` and `Parent` ticket types
- Built-in types cannot be deleted
- Built-in types may be renamed for display
- Additional custom ticket types may be added per project

### TicketPriority

Represents a project-specific priority label.

Required properties:

- Project
- Label
- Position

### TicketFieldDefinition

Represents one configurable field definition for tickets in a project.

Required properties:

- Project
- Label
- Field type

Initial field types:

- User
- Number

Future-safe expectation:

- The field type system is extensible

### TicketLinkType

Represents a project-specific label for linking tickets.

Required properties:

- Project
- Label

### TicketLink

Represents a relationship between two tickets.

Required properties:

- Source ticket
- Target ticket
- Link type

Behavior:

- Tickets expose linked tickets as a list
- The first documented product version only requires label-based linking

### WorklogEntry

Represents one audit-trail record for a ticket change.

Required properties:

- Ticket
- Actor user
- Change type
- Change summary
- Timestamp

### RepositoryConnection

Represents a project-level external repository configuration.

Required properties:

- Project
- Provider
- Repository identifier

Initial provider:

- Gitea

Future providers:

- GitHub
- GitLab

### BranchReference

Represents a branch associated with a ticket through a repository connection.

Required properties:

- Ticket
- Repository connection
- Branch name

### PullRequestReference

Represents a pull request associated with a ticket through a repository connection.

Required properties:

- Ticket
- Repository connection
- Pull request identifier
- Pull request title

## Relationships

- A user may belong to many teams.
- A team may contain many users.
- A project has many board columns.
- A project has many tickets.
- A project has many ticket type definitions.
- A project has many priority definitions.
- A project has many field definitions.
- A project has many link type definitions.
- A project has many repository connections.
- A ticket belongs to exactly one project.
- A ticket may have zero or one parent ticket.
- A ticket may have many child tickets.
- A ticket may have many worklog entries.
- A ticket may have many links to other tickets.
- A ticket may have many future branch references.
- A ticket may have many future pull request references.

## Invariants

### Project key and ticket key

- Project key length must not exceed 5 characters.
- Project key is normalized to uppercase.
- Project key must be unique across the application.
- Ticket key format is `PROJECTKEY-INDEX`.
- `INDEX` is unique within a project and increases monotonically.
- Ticket key is immutable after creation.

### Ticket lifecycle

- Every new ticket starts in the backlog.
- A ticket appears on the board only when assigned to a board column.
- Board column assignment must belong to the same project as the ticket.

### Ticket hierarchy

- A ticket may reference only one parent ticket.
- A parent reference is optional.
- Only a ticket whose type is `Parent` may be used as a parent target.
- A `Task` ticket may have a parent but may not be the parent of another ticket.
- Any custom non-`Parent` type may have a parent but may not be the parent of another ticket.
- A `Parent` ticket may itself have a parent, enabling nested parent trees.

### Ticket metadata

- Title is required and not unique.
- Description is part of the ticket record.
- Acceptance criteria is part of the ticket record.
- Priority must be one of the project's configured priority definitions.
- Type must be one of the project's configured ticket type definitions.
- Custom field values must conform to the selected field definition type.

### Blocked state

- A blocked ticket requires a non-empty comment.
- Blocked state must be reflected in board presentation.

### Worklog

- Every ticket change creates a corresponding worklog entry.
- Every worklog entry records the acting user.

### Permission inheritance

- Effective project permissions are evaluated per project.
- Direct user permissions and inherited team permissions are cumulative.
- Global admin access is evaluated separately from project permissions.

### Git references

- Branch and pull request matching is based on ticket-key-prefixed names.
- A reference is associated with a ticket when the branch name starts with that ticket's key.

## Canonical terminology

Use these terms consistently in future implementation work:

- `Project`
- `Project Key`
- `Ticket`
- `Ticket Key`
- `Board`
- `Board Column`
- `Backlog`
- `Parent Ticket`
- `Worklog Entry`
- `Repository Connection`