codex - added docu

docs/domain-model.md

@@ -0,0 +1,322 @@
+# 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`