From 6dee323c6c46a206a6e525853c61ab7024e47f93 Mon Sep 17 00:00:00 2001 From: Twyco Date: Wed, 25 Mar 2026 00:01:02 +0100 Subject: [PATCH] codex - added docu --- docs/README.md | 41 +++++ docs/architecture-roadmap.md | 221 ++++++++++++++++++++++++ docs/domain-model.md | 322 +++++++++++++++++++++++++++++++++++ docs/product-spec.md | 272 +++++++++++++++++++++++++++++ 4 files changed, 856 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/architecture-roadmap.md create mode 100644 docs/domain-model.md create mode 100644 docs/product-spec.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..df7bdae --- /dev/null +++ b/docs/README.md @@ -0,0 +1,41 @@ +# KanbanGit Documentation + +## Current status + +KanbanGit currently starts from a fresh Laravel 13 + Inertia starter application. The product-specific Kanban, ticketing, permission, and Git integration features described in this documentation are not implemented yet. + +## Product summary + +KanbanGit is intended to become a self-hostable project management application with Kanban workflows and Git provider integrations. The long-term product direction is comparable to a lightweight Jira-style workflow system with repository awareness, starting with Gitea and leaving room for future providers such as GitHub and GitLab. + +The product centers around projects. Each project owns its own board configuration, backlog, ticket metadata, ticket hierarchy, and repository connections. The architecture must support application-wide administration plus project-scoped permissions that can be assigned to users and teams. + +## Documentation map + +- [Product Spec](/docs/product-spec.md) describes expected product behavior, user-visible rules, and scope boundaries. +- [Domain Model](/docs/domain-model.md) defines the canonical domain concepts, relationships, and invariants that future database tables, Eloquent models, policies, and frontend types should follow. +- [Architecture Roadmap](/docs/architecture-roadmap.md) captures the planned architecture direction, permission strategy, integration boundaries, and staged implementation intent. + +## Glossary + +| Term | Meaning | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| Project | A workspace with its own settings, board columns, backlog, tickets, and repository connections. | +| Project Key | A project-specific uppercase identifier with a maximum length of 5 characters. It prefixes every ticket key. | +| Ticket Key | The immutable unique ticket identifier in the format `PROJECTKEY-INDEX`. | +| Board | The Kanban view of a project, using configurable project-specific columns. | +| Backlog | The default intake area where newly created tickets start before they are moved into a board column. | +| Ticket | The core work item with title, description, acceptance criteria, type, priority, status, custom field values, worklog, and links. | +| Parent Ticket | A ticket of the dedicated `Parent` type that may contain child tickets. | +| Worklog | The audit trail of ticket changes, including what changed and who changed it. | +| Team | A group of users that can receive project permissions and pass those permissions to its members. | +| Permission | A project-scoped action grant such as `create`, `view`, `edit`, or `delete`, plus application-wide admin access for platform administration. | +| Repository Connection | A project-level configuration that links the project to an external Git provider repository. | + +## Product principles + +- Self-hosting is a core requirement. +- Projects are the primary boundary for workflow configuration. +- Ticket keys are immutable and must remain reliable references across the product and future Git integrations. +- Permissions must be designed for both direct user assignment and team inheritance, even before the full permission system is implemented. +- External Git providers must be introduced behind a provider abstraction, even if Gitea is the first supported provider. diff --git a/docs/architecture-roadmap.md b/docs/architecture-roadmap.md new file mode 100644 index 0000000..fa69406 --- /dev/null +++ b/docs/architecture-roadmap.md @@ -0,0 +1,221 @@ +# KanbanGit Architecture Roadmap + +## Purpose + +This document captures the intended architecture direction for KanbanGit so that implementation can start with stable boundaries and without re-deciding the core domain model later. + +## Current state + +The current repository is still a fresh Laravel 13 + Inertia starter application with authentication scaffolding. The architecture described here is target-state guidance and not a description of the current implementation. + +## Architectural goals + +- Keep the product self-hostable and simple to operate. +- Preserve a clear separation between platform administration and project-scoped work. +- Make project workflow configuration flexible without coupling it to one fixed board model. +- Treat ticket keys as first-class stable references across UI, worklog, and future Git integrations. +- Introduce Git providers behind a provider abstraction so the product does not become Gitea-specific at the domain level. + +## Recommended domain boundaries + +The application should evolve around these bounded areas: + +- Administration +- Identity and access +- Projects +- Ticketing +- Integrations + +### Administration + +Owns: + +- Global settings +- User administration +- Platform admin capabilities + +### Identity and access + +Owns: + +- Users +- Teams +- Permission definitions +- Direct permission assignments +- Team-based permission inheritance + +The permission architecture must support both of these layers: + +- Global admin access +- Project-scoped permissions + +### Projects + +Owns: + +- Project creation and lifecycle +- Project key rules +- Board column configuration +- Ticket type configuration +- Ticket priority configuration +- Ticket field configuration +- Ticket link type configuration +- Repository connection configuration + +### Ticketing + +Owns: + +- Backlog +- Board placement +- Ticket creation and editing +- Parent-child hierarchy +- Blocked state +- Worklog +- Ticket linking + +### Integrations + +Owns: + +- Git provider abstraction +- Provider-specific repository sync or discovery logic +- Branch and pull request correlation to tickets + +## Permission architecture direction + +The permission system is intentionally not implemented in this step, but the rest of the application should be designed so it can be introduced without structural rework. + +Key rules: + +- Application-wide admin access is separate from project-scoped permissions. +- Project permissions are at least `create`, `view`, `edit`, and `delete`. +- Permissions can be granted directly to users. +- Permissions can be granted to teams. +- Users inherit project permissions through team membership. +- Effective permissions are additive. + +Implementation guidance: + +- Avoid hard-coding authorization rules directly into project or ticket records. +- Keep permission evaluation as a dedicated capability that can later be expressed through policies or services. +- Model team inheritance as a first-class rule, not as a future patch. + +## Project configuration direction + +Projects must be the configuration boundary for workflow behavior. + +Each project should eventually own: + +- A globally unique project key +- Board columns +- Ticket types +- Ticket priorities +- Ticket field definitions +- Ticket link types +- Repository connections + +This allows each project to define its own working style without requiring application-wide workflow rules. + +## Ticket architecture direction + +Ticketing should be designed around a stable core record plus project-configured metadata. + +Stable ticket core: + +- Ticket key +- Title +- Description +- Acceptance criteria +- Status context +- Type +- Priority +- Parent reference +- Blocked state + +Project-configured metadata: + +- User fields such as assignee, driver, reviewer, and reporter +- Numeric fields such as estimated story points +- Future additional field types + +History model: + +- Every ticket change writes to a worklog entry stream +- Worklog captures actor and change summary +- Worklog should be treated as part of the core ticket experience, not an optional add-on + +Hierarchy model: + +- Parent-child relationships are explicit +- Only `Parent` tickets can act as parent nodes +- Nested parent trees are allowed + +## Git integration direction + +The first planned integration target is Gitea. The architecture should still avoid provider-specific assumptions in core ticketing or project logic. + +Required direction: + +- Repository connections live in project settings +- A project may eventually connect multiple repositories +- Provider information belongs to the repository connection layer +- Ticket views later expose branches and pull requests +- Matching is based on branch names that start with the ticket key + +Future providers: + +- GitHub +- GitLab + +## Suggested implementation phases + +### Phase 1 + +Foundation only: + +- Projects +- Project keys +- Backlog +- Board columns +- Tickets +- Ticket priorities +- Ticket types +- Ticket field definitions +- Ticket links +- Blocked state +- Worklog + +### Phase 2 + +Access control foundation: + +- Teams +- Project permissions +- Admin permissions +- Effective permission evaluation + +### Phase 3 + +Git integration foundation: + +- Gitea repository connections +- Branch correlation +- Pull request correlation + +### Phase 4 + +Later expansion: + +- Additional Git providers +- Roadmap +- Other planning and reporting capabilities + +## Explicitly not implemented in this step + +- No database schema has been added yet. +- No Eloquent models have been added yet. +- No policies or permission evaluation logic have been added yet. +- No board, backlog, project, or ticket UI has been added yet. +- No Git integration has been added yet. +- No roadmap feature has been added yet. diff --git a/docs/domain-model.md b/docs/domain-model.md new file mode 100644 index 0000000..a3e1bcd --- /dev/null +++ b/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` diff --git a/docs/product-spec.md b/docs/product-spec.md new file mode 100644 index 0000000..6fe862e --- /dev/null +++ b/docs/product-spec.md @@ -0,0 +1,272 @@ +# KanbanGit Product Specification + +## Purpose + +KanbanGit is a self-hostable project and workflow management application. Its initial product goal is to support project-based Kanban work management with configurable board structure, configurable ticket metadata, ticket hierarchy, auditability, and a future repository integration workflow. + +This document describes the intended product behavior. It does not claim that these capabilities exist in the current fresh Laravel 13 starter application. + +## Current implementation status + +- The repository currently contains the default Laravel 13 + Inertia starter structure. +- No Kanban, ticket, permission, team, project, or Git integration domain has been implemented yet. +- This specification is the source of truth for the upcoming product implementation. + +## Product goals + +- Support multiple projects inside one self-hosted installation. +- Provide a configurable board and backlog per project. +- Support tickets with structured metadata, hierarchy, linking, blockers, and change history. +- Support application administration and project-level access control. +- Prepare the product for repository-aware workflows, starting with Gitea. + +## Roles + +### Platform admin + +A platform admin can manage application-wide administrative settings and user administration. This role exists above project-level permissions. + +### Project member + +A project member may receive project permissions directly or through one or more teams. Project permissions are scoped to a single project. + +## Project behavior + +Each project must include the following product areas: + +- Board +- Backlog +- Project settings +- Ticket management +- Future roadmap support + +### Project creation + +When a project is created, it must define: + +- A project name +- A project key + +Project key rules: + +- Maximum length: 5 characters +- Automatically stored and displayed in uppercase +- Unique across the entire application +- Immutable after ticket creation begins, unless a future migration strategy is explicitly designed + +The project key is used as the prefix for all ticket keys in that project. + +## Board and backlog + +Each project has one board and one backlog. + +Board rules: + +- The board supports any number of columns. +- Board columns are configured in project settings. +- Board columns define the valid in-board statuses for tickets. + +Backlog rules: + +- Every newly created ticket starts in the backlog. +- A backlog ticket is not yet visible in the board columns. +- When a ticket is assigned to a board column status, it appears on the board. +- Tickets may move between backlog and board statuses according to future workflow rules. + +## Roadmap + +Roadmap support belongs to the intended product surface of a project, but it is currently out of scope for the first implementation phases. + +## Ticket behavior + +Tickets are the primary work items inside a project. + +### Required ticket attributes + +Every ticket must support: + +- Immutable ticket key +- Title +- Description +- Acceptance criteria +- Status +- Type +- Priority +- Optional parent ticket +- Configurable project-defined field values +- Links to other tickets +- Blocked state with comment +- Worklog +- Future branch references +- Future pull request references + +### Ticket key + +Ticket keys follow the format `PROJECTKEY-INDEX`. + +Rules: + +- `PROJECTKEY` is the uppercase project key. +- `INDEX` is a monotonically increasing project-local integer sequence. +- The full ticket key is immutable. +- Ticket title is not unique. +- Multiple tickets may share the same title, even within the same project. +- The ticket key is the only guaranteed unique human-readable identifier for a ticket. + +### Ticket status + +Tickets support two status contexts: + +- `Backlog` +- One configured board column + +Only tickets assigned to a board column appear on the board. + +### Ticket type + +Each project can configure its own ticket type labels in project settings. Two types must always exist: + +- `Task` +- `Parent` + +Rules: + +- `Task` and `Parent` are built-in types. +- Built-in types cannot be deleted. +- Built-in types may be renamed per project. +- Additional custom types may be added per project. +- Tickets of any type may have a parent ticket. +- Only tickets of type `Parent` may act as the parent of another ticket. + +### Ticket hierarchy + +Hierarchy rules: + +- A ticket may have zero or one parent ticket. +- A parent ticket must be a ticket whose type is `Parent`. +- A parent ticket may itself have a parent ticket. +- This allows nested parent structures. +- Parent tickets must show their child tickets in a list. +- Nested child structures should be presented with indentation or another clear hierarchy indicator. + +### Ticket priority + +Each project defines its own list of priorities in project settings. + +Rules: + +- The available priority options are project-specific. +- A ticket stores one priority value from the project's configured list. + +### Configurable ticket fields + +Each project may define additional ticket field definitions in project settings. + +A field definition includes at least: + +- Label +- Type + +Initial supported field-definition types include: + +- User +- Number + +Examples: + +- `Assignee` as a user field +- `Driver` as a user field +- `Reviewer` as a user field +- `Reporter` as a user field +- `Estimated Story Points` as a number field + +The field system must be designed to support additional field types in the future. + +### Ticket links + +Tickets may be linked to other tickets. + +Rules: + +- Link types are project-configurable labels. +- A linked ticket is represented as part of a ticket list on each side of the relationship. +- The implementation may later distinguish directionality, but the first documented requirement is label-based ticket linking configured per project. + +### Ticket blockers + +Tickets can be marked as blocked. + +Blocked rules: + +- Blocking requires a comment. +- Blocked tickets must be visually distinguished on the board. +- The target visual language is a warning or danger style such as orange or red. + +### Ticket worklog + +Each ticket must have a worklog. + +Worklog rules: + +- The worklog records every change to the ticket. +- Each worklog entry must record who performed the change. +- The worklog is part of the canonical ticket history. + +Expected worklog-triggering changes include: + +- Ticket creation +- Title, description, or acceptance criteria edits +- Status changes +- Type changes +- Priority changes +- Parent changes +- Custom field value changes +- Link changes +- Blocked or unblocked state changes + +## Permissions + +The product must support both global administration and project-scoped permissions. + +Global permission behavior: + +- Platform admins can manage application-wide administrative settings. +- Platform admins can manage users. + +Project permission behavior: + +- Project permissions include `create`, `view`, `edit`, and `delete`. +- Project permissions may be assigned directly to users. +- Project permissions may be assigned to teams. +- Users inherit project permissions from their teams. + +The full permission system is not implemented in this step, but the product must be built with this model in mind. + +## Future Git integration + +The next major feature after the Kanban foundation is Git provider integration. + +Initial expectations: + +- Project settings can store one or more repository connections. +- The first supported provider is Gitea. +- Later providers should include GitHub and potentially GitLab. +- Tickets will later expose branch and pull request sections. + +Ticket-to-Git matching rule: + +- A branch or pull request belongs to a ticket when its branch name starts with the ticket key. + +Example: + +- Ticket key: `AUTH-42` +- Matching branch: `AUTH-42-login-form` + +## Explicitly out of scope for now + +- Implementing roadmap features +- Supporting GitHub or GitLab in the first Git integration step +- Implementing the full permission and team management UI in this documentation step +- Finalizing database schema details +- Finalizing API contracts +- Finalizing automation, notifications, or reporting features