Skip to content

Roadmap Item: Issue Tracking Service

Status

PROPOSED

Date: 2026-02-17

Changelog

Date Revision Description Author
2026-02-17 1.0 Initial version Loryth Team

Context

The loryth-issues service currently has a basic skeleton with six migrations (v00–v05) covering Issue, Project, Status, Workflow, and IssueType entities. While the foundation exists — configurable workflows with transition validation, hierarchical issues via self-referencing parent_id, and event sourcing for core state changes — the service is far from a usable issue tracker.

Missing capabilities include: Space-scoped catalogs, boards (Kanban and Scrum), sprints, threaded comments, file attachments, issue links, labels/tags, acceptance criteria checklists, custom fields, drag-and-drop ranking, full audit history, soft delete with restore, search, and reporting. Essentially everything needed to manage real projects at scale.

Without these features, the platform cannot offer a competitive project management experience. Teams need configurable workflows, visual boards, collaboration tools, and insight into their delivery metrics.

Proposal

Overview

Evolve loryth-issues from its current skeleton into a complete issue tracking service with configurable workflows, visual boards, sprint management, rich collaboration features, full audit trails, and reporting — delivered in four incremental phases.

Goals

  • Complete issue tracker with configurable workflows and type-based hierarchy constraints
  • Visual board system supporting both Kanban and Scrum methodologies
  • Sprint management with backlog, active sprint, and completion workflows
  • Collaboration: threaded comments, attachments, @mentions, issue links, acceptance criteria checklists
  • Full audit trail: field-level change history, activity log, soft delete with restore
  • Reporting: velocity, cycle time, epic progress, bugs-in-progress
  • Search: delegated to the ai-service for semantic search capabilities
  • Space-scoped catalogs for multi-tenant isolation of statuses, workflows, types, and custom fields

Non-Goals

  • Detailed permission model beyond Space-level scoping (future work)
  • Attachment storage backend implementation (uses TDD-0002 file storage interfaces)
  • Compliance or regulatory audit features
  • Real-time collaborative editing of issue descriptions
  • Full-text search infrastructure within loryth-issues (delegated to ai-service)
  • Space entity ownership (owned by future core-platform service)

Technical Details

Approach

The implementation extends the existing entity model rather than replacing it. All current tables (status, workflow, workflow_transition, issue_type, project, issue) are preserved and evolved with new columns and relationships.

Key architectural decisions are documented in ADR-0016:

  • Space-scoped catalogs via space_id: UUID FK on all catalog entities
  • LexoRank ordering for drag-and-drop issue reordering
  • Auto-walk transitions using BFS through the workflow graph
  • Board columns with primary drop status for deterministic drag behavior
  • Type hierarchy constraints per project for flexible parent-child rules
  • EAV model for custom fields with typed value columns
  • Soft delete with deleted_at timestamp and restore capability
  • Search delegation to ai-service via RabbitMQ events

Dependencies

Backwards Compatibility

  • Existing migrations (v00–v05) are preserved; new migrations extend the schema
  • Existing API endpoints evolve with additional fields (additive, non-breaking)
  • space_id columns on existing entities require a data migration for pre-existing records
  • Issue keys (PROJ-123) are a new concept — existing issues will need backfill

Implementation Plan

Phase 1: Core Domain and Data Model

  • Add space_id: UUID to Status, Workflow, IssueType, Project
  • Create CustomFieldDefinition entity (Space-scoped)
  • Create LinkTypeDefinition entity (Space-scoped)
  • Create ProjectConfiguration entities (ProjectIssueType, ProjectCustomField, ProjectLinkType)
  • Create TypeHierarchyRule entity
  • Redesign Issue aggregate: add issue_type_id, assignee_id, reporter_id, priority, rank, issue_number, issue_key, start_date, due_date, sprint_id, deleted_at
  • Implement project key + issue number sequence for immutable issue keys
  • Create CustomFieldValue entity (EAV)
  • Write SQL migrations for all new/modified tables
  • Update existing CRUD services and API endpoints

Phase 2: Workflow Engine and Board System

  • Implement workflow transition validation with auto-walk (BFS shortest path)
  • Create Board entity with columns and column-status mappings
  • Implement primary drop status logic for board columns
  • Add swimlane configuration (by assignee, priority, type)
  • Implement LexoRank ordering with between-rank generation
  • Add rank rebalancing background job
  • Create Sprint model with planned/active/completed lifecycle
  • Implement backlog view (issues not in any sprint)
  • Auto-set start_date when entering "in progress" statuses
  • Build board and sprint API endpoints

Phase 3: Collaboration Features

  • Implement threaded comments with arbitrary nesting depth
  • Add comment edit history (every edit preserved)
  • Create attachment metadata model (references TDD-0002)
  • Implement labels/tags with categories and single-select enforcement
  • Create issue links with directed and symmetric link types
  • Implement checklist/acceptance criteria items with LexoRank ordering
  • Add @mention parsing and notification dispatch via RabbitMQ
  • Build collaboration API endpoints

Phase 4: Audit, Search and Reporting

  • Implement activity log with user-visible event timeline
  • Add field-level change history for complete audit trail
  • Implement soft delete with deleted_at and restore endpoint
  • Cascade soft delete to child issues
  • Publish search indexing events to ai-service via RabbitMQ
  • Implement search proxy endpoint with SQL ILIKE fallback
  • Build reporting endpoints: velocity, cycle time, epic progress, bugs-in-progress
  • Add deleted issues listing endpoint for restore workflow

Community Impact

For Contributors

  • Understanding of the layered architecture (routers → services → repositories → aggregates)
  • Familiarity with the DI framework (DiContainerBuilder, @transactional)
  • Knowledge of LexoRank algorithm for ranking features
  • Understanding of BFS for workflow auto-walk implementation

For Users

  • Full project management with configurable workflows and visual boards
  • Sprint planning with backlog management and velocity tracking
  • Rich collaboration through comments, attachments, and @mentions
  • Complete audit trail for accountability and compliance
  • Semantic search across issues and comments

Alternatives Considered

  1. Replace loryth-issues entirely

    • Description: Build a new service from scratch with a clean data model
    • Pros: Clean slate, no migration concerns
    • Cons: Wastes existing work, longer timeline, migration complexity
    • Why not chosen: The existing skeleton is well-structured and extensible

  2. Integrate an existing open-source issue tracker

    • Description: Embed or wrap an existing solution (e.g., Plane, Huly)
    • Pros: Faster time to feature parity
    • Cons: Tight coupling, limited customization, different tech stack
    • Why not chosen: Platform consistency and full control over the domain model

  3. CQRS with separate read/write models

    • Description: Separate command and query models for scalability
    • Pros: Better read performance, flexible projections
    • Cons: Significant complexity increase, eventual consistency challenges
    • Why not chosen: Premature optimization — standard CRUD with strategic denormalization is sufficient for current scale

Open Questions

  • Exact retention period for hard-deleting soft-deleted issues (default 30 days proposed)
  • Whether custom field values should be searchable via ai-service
  • Notification preferences granularity (per-project, per-event-type, or global)
  • Whether board configurations should be shareable across projects within a Space

References