Loryth Issues Service Documentation¶

Domain Overview¶

The Loryth Issues service manages issues, projects, workflows, and statuses. It provides a flexible system for tracking and managing issues through customizable workflows. This documentation describes the core domains and their relationships.

Domain Models¶

Issue¶

Issue represents a task, bug, feature, or any other work item that needs to be tracked. Issues can have parent-child relationships, allowing for hierarchical organization.

classDiagram
    class Issue {
        +UUID id
        +int project_id
        +int status_id
        +int parent_id
        +DateTime createdAt
        +DateTime updatedAt
    }

    Issue "1" --> "0..1" Issue : parent
    Issue "1" --> "*" Issue : children

Key Characteristics: - Issues belong to a project - Issues have a status that reflects their current state - Issues can have parent-child relationships - Issues can be moved between projects - Issues can change status according to workflow rules

Project¶

Project represents a container for issues. It provides organizational structure and context.

classDiagram
    class Project {
        +UUID id
        +UUID owner_id
        +String name
        +UUID cms_node_id
        +DateTime createdAt
        +DateTime updatedAt
    }

Key Characteristics: - Projects have an owner - Projects have a name - Projects have a reference to a CMS node for description - Projects can contain multiple issues

Status¶

Status represents a distinct state that an issue can be in. Statuses are independent entities that can be shared across multiple workflows.

classDiagram
    class Status {
        +UUID id
        +UUID owner_id
        +String title
        +UUID description_node_id
        +UiMetadata ui
        +DateTime createdAt
        +DateTime updatedAt
    }

Key Characteristics: - Statuses are immutable once created - Statuses have universal meaning across the system - Common statuses: "Open", "In Progress", "Done" - Statuses can be referenced by multiple workflows - Statuses maintain their own UI metadata for display purposes

IssueType¶

IssueType represents a category or classification of issues. Different issue types can follow different workflows.

classDiagram
    class IssueType {
        +UUID id
        +UUID owner_id
        +String name
        +UUID cms_node_id
        +int workflow_id
        +UiMetadata ui
        +DateTime createdAt
        +DateTime updatedAt
    }

Key Characteristics: - Issue types have an owner - Issue types have a name - Issue types have a reference to a CMS node for description - Issue types are associated with a specific workflow - Issue types maintain their own UI metadata for display purposes

Workflow¶

Workflow defines valid transitions between statuses, effectively creating a state machine configuration.

classDiagram
    class Workflow {
        +UUID id
        +UUID owner_id
        +String title
        +UUID description_node_id
        +UiMetadata ui
        +DateTime createdAt
        +DateTime updatedAt
        +List~WorkflowTransition~ transitions
    }

    class WorkflowTransition {
        +int id
        +int workflow_id
        +int source_id
        +int target_id
        +String condition
    }

    Workflow "1" *-- "*" WorkflowTransition
    WorkflowTransition --> "1" Status : source
    WorkflowTransition --> "1" Status : target

Key Characteristics: - Workflows define allowed status transitions - Transitions can have optional conditions - Multiple workflows can use the same statuses - Workflows belong to specific owners (projects/organizations)

Domain Map¶

The following diagram shows the relationships between all domain entities:

classDiagram
    class Issue {
        +UUID id
        +int project_id
        +int status_id
        +int parent_id
    }

    class Project {
        +UUID id
        +UUID owner_id
        +String name
        +UUID cms_node_id
    }

    class Status {
        +UUID id
        +UUID owner_id
        +String title
        +UUID description_node_id
        +UiMetadata ui
    }

    class IssueType {
        +UUID id
        +UUID owner_id
        +String name
        +UUID cms_node_id
        +int workflow_id
        +UiMetadata ui
    }

    class Workflow {
        +UUID id
        +UUID owner_id
        +String title
        +UUID description_node_id
        +UiMetadata ui
        +List~WorkflowTransition~ transitions
    }

    class WorkflowTransition {
        +int id
        +int workflow_id
        +int source_id
        +int target_id
        +String condition
    }

    Issue "1" --> "0..1" Issue : parent
    Issue "1" --> "*" Issue : children
    Issue "*" --> "1" Project : belongs to
    Issue "*" --> "1" Status : current status
    IssueType "*" --> "1" Workflow : follows
    Workflow "1" *-- "*" WorkflowTransition
    WorkflowTransition --> "1" Status : source
    WorkflowTransition --> "1" Status : target

Example State Flow¶

stateDiagram-v2
    [*] --> Open
    Open --> InProgress: Start Work
    InProgress --> Review: Submit
    Review --> InProgress: Request Changes
    Review --> Done: Approve
    Done --> [*]

Domain Rules¶

Issue Rules¶

1. Issues must belong to a project
2. Issues must have a status
3. Issues can have a parent issue
4. Issues can have multiple child issues
5. Issues can only transition to statuses allowed by their workflow

Project Rules¶

1. Projects must have an owner
2. Projects must have a name
3. Projects must have a description

Status Rules¶

1. Statuses cannot be deleted if they are used in any workflow
2. Status titles must be unique within the system
3. Statuses must have a description
4. Statuses can be archived but not deleted if in use

IssueType Rules¶

1. Issue types must have an owner
2. Issue types must have a name
3. Issue types must have a description
4. Issue types must be associated with a workflow

Workflow Rules¶

1. Workflows must have at least one state
2. Transitions must reference existing states
3. Transitions cannot create cycles unless explicitly allowed
4. Workflows can be versioned but existing issues continue with their original workflow version

API Reference¶

The API for the Loryth Issues service is currently under development. Once implemented, this section will provide detailed information about available endpoints, request/response formats, and authentication requirements.