KanbanGit/docs/architecture-roadmap.md

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
• Ticket-driven branch creation

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.