# ehsanrs2/projectctl architecture

> Architecture diagram of the GitHub repository ehsanrs2/projectctl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ehsanrs2/projectctl
- Repository: https://github.com/ehsanrs2/projectctl

## Overview

ProjectCTL is a local-first, Git-native control plane for AI-assisted engineering. Its user workflow begins with project onboarding and task-authority selection, then gathers task and quota state for deterministic planning, governs isolated worker execution, independently verifies results, and controls evidence-based integration or recovery. Separate capabilities include parallel execution, project health checks, task-system integrations, and read-only lifecycle auditing. The graph uses documented product flows and source-index references; unsampled implementation details are represented only at supported directory paths, and the M6 trace collector remains explicitly unavailable.

Main entry points: [`projectctl/cli/app.py`](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/cli/app.py) (CLI Commands), [`projectctl/application/execution.py`](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/application/execution.py) (Run Lifecycle), [`projectctl/scheduler/service.py`](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/scheduler/service.py) (Quota-aware Scheduler), [`projectctl/storage/runs.py`](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/storage/runs.py) (Run State Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_cli["CLI Commands<br/>[app.py]"]
  node_onboarding["Project Onboarding<br/>[onboarding.py]"]
end

subgraph group_planning["Planning and Governance"]
  node_project["Project Config and State<br/>[loader.py]"]
  node_taskcapture["Task Snapshot<br/>[tasks.py]"]
  node_scheduler["Quota-aware Scheduler<br/>[service.py]"]
  node_quota["Quota Policy<br/>[manager.py]"]
  node_parallel["Parallel Planning<br/>[service.py]"]
end

subgraph group_execution["Execution and Evidence"]
  node_execution["Run Lifecycle<br/>[execution.py]"]
  node_worker["Worker Adapters"]
  node_verification["Independent Verification<br/>[runner.py]"]
  node_delivery["Review and Delivery<br/>[review_delivery.py]"]
end

subgraph group_integrations["Authority and Delivery"]
  node_taskauthority["Task Authority<br/>[task_authority.py]"]
  node_taskproviders["Task Providers"]
  node_git["Git Operations"]
end

subgraph group_operations["State and Observability"]
  node_runstore[("Run State Store<br/>[runs.py]")]
  node_doctor["Project Health Checks<br/>[service.py]"]
  node_audit["Lifecycle Audit"]
  node_trace["Trace Snapshot<br/>[snapshot.py]"]
end

node_engineer(("Engineer"))
node_external_tasks["Task Systems"]

node_engineer -->|"invokes"| node_cli
node_cli -->|"starts setup"| node_onboarding
node_cli -->|"requests tasks"| node_taskcapture
node_cli -->|"requests checks"| node_doctor
node_cli -->|"requests audit"| node_audit
node_onboarding -->|"configures project"| node_project
node_taskcapture -->|"resolves reader"| node_taskauthority
node_taskauthority -->|"selects provider"| node_taskproviders
node_taskproviders -.->|"reads tasks"| node_external_tasks
node_scheduler -->|"evaluates quota"| node_quota
node_scheduler -.->|"uses task snapshot"| node_taskcapture
node_scheduler -->|"uses project state"| node_project
node_scheduler -.->|"recommends work"| node_execution
node_parallel -->|"builds plan from"| node_project
node_execution -.->|"dispatches worker"| node_worker
node_execution -.->|"records lifecycle"| node_runstore
node_execution -.->|"requests verification"| node_verification
node_execution -->|"governs integration"| node_delivery
node_delivery -->|"uses Git delivery"| node_git
node_verification -.->|"records evidence"| node_runstore
node_audit -.->|"reads run history"| node_runstore
node_trace -->|"reads run data"| node_runstore

click node_cli "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/cli/app.py"
click node_onboarding "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/application/onboarding.py"
click node_project "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/project/loader.py"
click node_taskcapture "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/application/tasks.py"
click node_taskauthority "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/integrations/task_authority.py"
click node_taskproviders "https://github.com/ehsanrs2/projectctl/tree/main/projectctl/integrations"
click node_scheduler "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/scheduler/service.py"
click node_quota "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/quota/manager.py"
click node_parallel "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/parallel/service.py"
click node_execution "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/application/execution.py"
click node_worker "https://github.com/ehsanrs2/projectctl/tree/main/projectctl/workers"
click node_verification "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/verification/runner.py"
click node_delivery "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/application/review_delivery.py"
click node_git "https://github.com/ehsanrs2/projectctl/tree/main/projectctl/git"
click node_runstore "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/storage/runs.py"
click node_doctor "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/doctor/service.py"
click node_audit "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/telemetry/lifecycle_reader.py"
click node_trace "https://github.com/ehsanrs2/projectctl/blob/main/projectctl/trace/snapshot.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_onboarding toneBlue
class node_project,node_taskcapture,node_scheduler,node_quota,node_parallel toneAmber
class node_execution,node_worker,node_verification,node_delivery toneMint
class node_taskauthority,node_taskproviders,node_git,node_external_tasks toneRose
class node_runstore,node_doctor,node_audit,node_trace,node_engineer toneIndigo
```

## Components

### User Entry

- [CLI Commands](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/cli/app.py): `projectctl/cli/app.py`
- [Project Onboarding](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/application/onboarding.py): `projectctl/application/onboarding.py`

### Planning and Governance

- [Project Config and State](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/project/loader.py): `projectctl/project/loader.py`
- [Task Snapshot](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/application/tasks.py): `projectctl/application/tasks.py`
- [Quota-aware Scheduler](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/scheduler/service.py): `projectctl/scheduler/service.py`
- [Quota Policy](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/quota/manager.py): `projectctl/quota/manager.py`
- [Parallel Planning](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/parallel/service.py): `projectctl/parallel/service.py`

### Execution and Evidence

- [Run Lifecycle](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/application/execution.py): `projectctl/application/execution.py`
- [Worker Adapters](https://github.com/ehsanrs2/projectctl/tree/main/projectctl/workers): `projectctl/workers`
- [Independent Verification](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/verification/runner.py): `projectctl/verification/runner.py`
- [Review and Delivery](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/application/review_delivery.py): `projectctl/application/review_delivery.py`

### Authority and Delivery

- [Task Authority](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/integrations/task_authority.py): `projectctl/integrations/task_authority.py`
- [Task Providers](https://github.com/ehsanrs2/projectctl/tree/main/projectctl/integrations): `projectctl/integrations`
- [Git Operations](https://github.com/ehsanrs2/projectctl/tree/main/projectctl/git): `projectctl/git`

### State and Observability

- [Run State Store](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/storage/runs.py): `projectctl/storage/runs.py`
- [Project Health Checks](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/doctor/service.py): `projectctl/doctor/service.py`
- [Lifecycle Audit](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/telemetry/lifecycle_reader.py): `projectctl/telemetry/lifecycle_reader.py`
- [Trace Snapshot](https://github.com/ehsanrs2/projectctl/blob/main/projectctl/trace/snapshot.py): `projectctl/trace/snapshot.py`

### Other components

- **Engineer**
- **Task Systems**

## Connections

- Engineer → CLI Commands: invokes (evidence: `README.md`)
- CLI Commands → Project Onboarding: starts setup (evidence: `projectctl/cli/app.py`)
- CLI Commands → Task Snapshot: requests tasks (evidence: `projectctl/cli/app.py`)
- CLI Commands → Project Health Checks: requests checks (evidence: `README.md`)
- CLI Commands → Lifecycle Audit: requests audit (evidence: `README.md`)
- Project Onboarding → Project Config and State: configures project
- Task Snapshot → Task Authority: resolves reader (evidence: `projectctl/application/tasks.py`)
- Task Authority → Task Providers: selects provider
- Task Providers → Task Systems: reads tasks
- Quota-aware Scheduler → Quota Policy: evaluates quota (evidence: `projectctl/scheduler/service.py`)
- Quota-aware Scheduler → Task Snapshot: uses task snapshot
- Quota-aware Scheduler → Project Config and State: uses project state (evidence: `projectctl/scheduler/service.py`)
- Quota-aware Scheduler → Run Lifecycle: recommends work
- Parallel Planning → Project Config and State: builds plan from (evidence: `projectctl/parallel/service.py`)
- Run Lifecycle → Worker Adapters: dispatches worker
- Run Lifecycle → Run State Store: records lifecycle
- Run Lifecycle → Independent Verification: requests verification
- Run Lifecycle → Review and Delivery: governs integration (evidence: `README.md`)
- Review and Delivery → Git Operations: uses Git delivery (evidence: `projectctl/application/review_delivery.py`)
- Independent Verification → Run State Store: records evidence
- Lifecycle Audit → Run State Store: reads run history
- Trace Snapshot → Run State Store: reads run data (evidence: `projectctl/trace/snapshot.py`)