Merge pull request 'codex - added docu' (#1) from codex/docu-setup into main

Reviewed-on: OpenSource/KanbanGit#1

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.

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.

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`

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