KanbanGit/docs/domain-model.md

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

Behavior:

• Branch matching is based on the ticket key prefix.
• The branch list may also be the entry point for creating a new branch from the ticket detail view.
• Branch creation depends on the current user's personal Git credentials for the selected repository connection.

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