223 lines
5.5 KiB
Markdown
223 lines
5.5 KiB
Markdown
# 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.
|