# 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.
- The ticket branch section should eventually allow users to create a new branch directly from the ticket detail view.

Ticket-to-Git matching rule:

- A branch or pull request belongs to a ticket when its branch name starts with the ticket key.

Branch creation expectations:

- The ticket detail view may expose a branch creation action inside the branch section.
- The branch creation flow should let the user choose from all project-linked repositories.
- Repository choices remain visible even when the current user has no matching personal Git connection.
- If the user lacks access to the selected repository, branch creation fields must stay disabled and guide the user to their Git connection settings.
- The suggested branch name should start from the ticket key plus a title-derived suffix and remain editable before creation.
- The UI should validate that the proposed branch name is syntactically acceptable and not already taken before creation is submitted.

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