codex - added docu
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user