Architecture overview

IssueSuite is a Python CLI that declaratively manages GitHub Issues from a single Markdown source of truth. This explanation summarises the core modules and data flow.

System architecture

graph TB
    subgraph "Input Layer"
        ISSUES[ISSUES.md<br/>Markdown Specs]
        CONFIG[issue_suite.config.yaml<br/>Configuration]
    end

    subgraph "CLI Layer"
        CLI[cli.py<br/>Command Parser]
        RUNTIME[runtime.py<br/>Execution Wrapper]
    end

    subgraph "Processing Layer"
        PARSER[parser.py<br/>Spec Parser]
        CORE[core.py<br/>Sync Engine]
        ORCH[orchestrator.py<br/>State Manager]
    end

    subgraph "Integration Layer"
        GH[github_issues.py<br/>REST Client]
        AUTH[github_auth.py<br/>Auth Provider]
        PROJ[project.py<br/>Projects v2]
        RETRY[retry.py<br/>Resilient Calls]
    end

    subgraph "Output Layer"
        MAPPING[.issuesuite/index.json<br/>Slug → Issue Mapping]
        SUMMARY[issues_summary.json<br/>Change Summary]
        TELEMETRY[Telemetry Events]
        PLUGINS[Plugin Hooks]
    end

    subgraph "External Systems"
        GITHUB[GitHub API]
        PROJECTS[GitHub Projects v2]
    end

    ISSUES --> PARSER
    CONFIG --> CLI
    CLI --> RUNTIME
    RUNTIME --> PARSER
    PARSER --> CORE
    CORE --> ORCH
    ORCH --> GH
    ORCH --> PROJ
    GH --> AUTH
    GH --> RETRY
    PROJ --> RETRY
    GH --> GITHUB
    PROJ --> PROJECTS
    ORCH --> MAPPING
    ORCH --> SUMMARY
    RUNTIME --> TELEMETRY
    RUNTIME --> PLUGINS

    style ISSUES fill:#e1f5ff
    style CONFIG fill:#e1f5ff
    style GITHUB fill:#fff3cd
    style PROJECTS fill:#fff3cd
    style MAPPING fill:#d4edda
    style SUMMARY fill:#d4edda

This diagram shows the complete data flow from Markdown specs through processing to GitHub integration and artifact generation.

High-level flow

sequenceDiagram
    participant User
    participant CLI
    participant Parser
    participant Core
    participant Orchestrator
    participant GitHub
    participant Files as Artifacts

    User->>CLI: issuesuite sync --update
    CLI->>Parser: Load ISSUES.md
    Parser->>Parser: Validate slug format
    Parser->>Parser: Parse YAML blocks
    Parser-->>Core: Issue specs

    Core->>Core: Load existing mapping
    Core->>GitHub: Fetch live issues
    GitHub-->>Core: Current state

    Core->>Core: Compute diff
    Core->>Core: Generate plan

    alt Dry Run
        Core-->>CLI: Plan with proposed changes
        CLI-->>User: Display plan
    else Update Mode
        Core->>Orchestrator: Execute plan
        Orchestrator->>GitHub: Create/Update/Close
        GitHub-->>Orchestrator: Results
        Orchestrator->>Files: Persist mapping
        Orchestrator->>Files: Write summary
        Orchestrator-->>CLI: Enriched summary
        CLI-->>User: Display results
    end

The sequence diagram above shows the typical sync workflow:

1. CLI (src/issuesuite/cli.py) parses arguments, loads configuration, and dispatches subcommands.
2. Runtime helpers (runtime.py) wrap command execution with telemetry emission and plugin invocation.
3. Core engine (core.py) parses specs, computes sync plans, and orchestrates GitHub mutations or mock-mode prints.
4. Orchestrator (orchestrator.py) persists mapping state, enriches summaries, and enforces diff truncation.
5. GitHub integration (github_issues.py, github_auth.py) centralises REST calls with resilient retries from retry.py.
6. Projects integration (project.py) optionally syncs into GitHub Projects v2 using cached metadata in .issuesuite_cache/.

ISSUES.md  -> parser -> plan builder -> GitHub client
   |            |             |               |
   |            v             v               v
   +--> SuiteConfig ----> orchestrator ----> telemetry/plugins

Key modules

Module	Responsibility
parser.py	Validates spec format and converts Markdown into structured issues.
core.py	Compares desired state with live issues and computes mutations.
orchestrator.py	Applies the plan, updates mappings, and returns enriched summaries.
runtime.py	Provides prepare_config and execute_command helpers so the CLI stays thin.
telemetry.py	Emits JSONL events when enabled, without affecting command success.
plugins.py	Discovers entry points/environment hooks and invokes them safely.
schemas.py	Generates JSON Schemas for exports and telemetry consumers.
scaffold.py	Implements the issuesuite init scaffolder.

Configuration lifecycle

graph LR
    subgraph "Configuration Sources"
        YAML[issue_suite.config.yaml]
        ENV[Environment Variables]
        CLI_ARGS[CLI Arguments]
    end

    subgraph "Resolution"
        LOAD[config.py loader]
        RESOLVE[Resolve $VAR syntax]
        MERGE[Merge overrides]
    end

    subgraph "Runtime"
        RUNTIME[runtime.py]
        EXEC[Command execution]
    end

    YAML --> LOAD
    ENV --> RESOLVE
    LOAD --> RESOLVE
    RESOLVE --> MERGE
    CLI_ARGS --> MERGE
    MERGE --> RUNTIME
    RUNTIME --> EXEC

    style YAML fill:#e1f5ff
    style ENV fill:#e1f5ff
    style CLI_ARGS fill:#e1f5ff

• config.py resolves environment variables using $VAR syntax before commands execute.
• Runtime overrides (--repo, --project-number) merge into the loaded config.
• Telemetry and plugin settings propagate into runtime helpers so instrumentation is opt-in.

Testing strategy

• Unit tests rely on mock mode (ISSUES_SUITE_MOCK=1) for determinism.
• CLI smoke tests exercise parsing, syncing, and schema generation end-to-end.
• Specialized suites cover parser edge cases, mapping persistence, project integration, and retry logic.

Planned features

We’re exploring first-class coverage for GitHub Projects automations so documentation will soon embed live dashboards and schema diffs generated by nightly quality gates.

For deeper dives see Extensions and plugins and Index mapping design.