# wyze69-sys/speccouncil architecture

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

- Interactive diagram: https://gitdiagram.com/wyze69-sys/speccouncil
- Repository: https://github.com/wyze69-sys/speccouncil

## Overview

SpecCouncil accepts a design, freezes it as evidence, runs four bounded specialist reviews, validates cited findings, persists results, and presents a deterministic report. The graph also shows the server-side preparation and worker path. The README documents the end-to-end contract; sampled source confirms key API, storage, review, and provider boundaries. Some internal dispatch details are unsampled, so those links are omitted rather than inferred.

Main entry points: [`internal/review/runner.go`](https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go) (Role runner), [`internal/storage/sqlite/store.go`](https://github.com/wyze69-sys/speccouncil/blob/master/internal/storage/sqlite/store.go) (Review store), [`internal/provider/provider.go`](https://github.com/wyze69-sys/speccouncil/blob/master/internal/provider/provider.go) (Provider boundary), [`internal/api/server.go`](https://github.com/wyze69-sys/speccouncil/blob/master/internal/api/server.go) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and ingestion"]
  node_httpapi["HTTP API<br/>[server.go]"]
  node_snapshotinput["Snapshot input"]
  node_ingest["Document ingestion<br/>[parser.go]"]
  node_evidence["Frozen evidence<br/>[snapshot.go]"]
end

subgraph group_execution["Review execution"]
  node_reviewrunner["Role runner<br/>[runner.go]"]
  node_prompting["Prompt assembly<br/>[prompt.go]"]
  node_validation["Finding validation<br/>[validate.go]"]
  node_provider["Provider boundary<br/>[provider.go]"]
  node_cline["Cline adapter<br/>[cline.go]"]
  node_fake["Scripted provider<br/>[fake.go]"]
  node_requirements["Requirements review<br/>[runner.go]"]
  node_architecture["Architecture review<br/>[runner.go]"]
  node_qa["QA review<br/>[runner.go]"]
  node_security["Security review<br/>[runner.go]"]
end

subgraph group_persistence["Persistence and workers"]
  node_sqlite[("Review store<br/>[store.go]")]
  node_preparation["Job preparation<br/>[prepare.go]"]
  node_supervisor["Worker supervision<br/>[supervise.go]"]
  node_dispatch["Role dispatch<br/>[dispatch.go]"]
  node_publication["Result publication<br/>[publish.go]"]
end

subgraph group_output["Reporting"]
  node_composer["Report composition<br/>[composer.go]"]
  node_reportread["Report and status reads<br/>[read.go]"]
end

node_submitter(("Design submitter"))
node_cline_service["Cline service"]

node_submitter -->|"submits design"| node_httpapi
node_httpapi -->|"submits review job"| node_sqlite
node_snapshotinput -->|"parses snapshot"| node_ingest
node_ingest -->|"freezes evidence"| node_evidence
node_sqlite -->|"prepares job"| node_preparation
node_evidence -->|"supplies shared snapshot"| node_reviewrunner
node_supervisor -.->|"coordinates work"| node_dispatch
node_dispatch -.->|"runs roles"| node_reviewrunner
node_reviewrunner -->|"assembles prompts"| node_prompting
node_reviewrunner -->|"calls provider"| node_provider
node_reviewrunner -->|"validates responses"| node_validation
node_provider -->|"implemented by"| node_cline
node_provider -->|"implemented by"| node_fake
node_cline -->|"sends model request"| node_cline_service
node_reviewrunner -->|"reviews requirements"| node_requirements
node_reviewrunner -->|"reviews architecture"| node_architecture
node_reviewrunner -->|"reviews testability"| node_qa
node_reviewrunner -->|"reviews security"| node_security
node_validation -->|"accepts cited findings"| node_publication
node_publication -->|"persists results"| node_sqlite
node_reviewrunner -->|"composes deterministic report"| node_composer
node_sqlite -->|"reads stored results"| node_reportread
node_reportread -->|"serves report"| node_httpapi

click node_httpapi "https://github.com/wyze69-sys/speccouncil/blob/master/internal/api/server.go"
click node_snapshotinput "https://github.com/wyze69-sys/speccouncil/blob/master/internal/api/snapshot_provider.go"
click node_ingest "https://github.com/wyze69-sys/speccouncil/blob/master/internal/ingest/parser.go"
click node_evidence "https://github.com/wyze69-sys/speccouncil/blob/master/internal/evidence/snapshot.go"
click node_sqlite "https://github.com/wyze69-sys/speccouncil/blob/master/internal/storage/sqlite/store.go"
click node_preparation "https://github.com/wyze69-sys/speccouncil/blob/master/internal/storage/sqlite/prepare.go"
click node_supervisor "https://github.com/wyze69-sys/speccouncil/blob/master/internal/worker/supervise.go"
click node_dispatch "https://github.com/wyze69-sys/speccouncil/blob/master/internal/worker/dispatch.go"
click node_reviewrunner "https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go"
click node_prompting "https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/prompt.go"
click node_validation "https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/validate.go"
click node_provider "https://github.com/wyze69-sys/speccouncil/blob/master/internal/provider/provider.go"
click node_cline "https://github.com/wyze69-sys/speccouncil/blob/master/internal/provider/cline/cline.go"
click node_fake "https://github.com/wyze69-sys/speccouncil/blob/master/internal/provider/fake/fake.go"
click node_composer "https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/composer.go"
click node_reportread "https://github.com/wyze69-sys/speccouncil/blob/master/internal/storage/sqlite/read.go"
click node_publication "https://github.com/wyze69-sys/speccouncil/blob/master/internal/storage/sqlite/publish.go"
click node_requirements "https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go"
click node_architecture "https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go"
click node_qa "https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go"
click node_security "https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go"

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_httpapi,node_snapshotinput,node_ingest,node_evidence toneBlue
class node_reviewrunner,node_prompting,node_validation,node_provider,node_cline,node_fake,node_requirements,node_architecture,node_qa,node_security toneAmber
class node_sqlite,node_preparation,node_supervisor,node_dispatch,node_publication toneMint
class node_composer,node_reportread toneRose
class node_submitter,node_cline_service toneIndigo
```

## Components

### Entry and ingestion

- [HTTP API](https://github.com/wyze69-sys/speccouncil/blob/master/internal/api/server.go): `internal/api/server.go`
- [Snapshot input](https://github.com/wyze69-sys/speccouncil/blob/master/internal/api/snapshot_provider.go): `internal/api/snapshot_provider.go`
- [Document ingestion](https://github.com/wyze69-sys/speccouncil/blob/master/internal/ingest/parser.go): `internal/ingest/parser.go`
- [Frozen evidence](https://github.com/wyze69-sys/speccouncil/blob/master/internal/evidence/snapshot.go): `internal/evidence/snapshot.go`

### Review execution

- [Role runner](https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go): `internal/review/runner.go`
- [Prompt assembly](https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/prompt.go): `internal/review/prompt.go`
- [Finding validation](https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/validate.go): `internal/review/validate.go`
- [Provider boundary](https://github.com/wyze69-sys/speccouncil/blob/master/internal/provider/provider.go): `internal/provider/provider.go`
- [Cline adapter](https://github.com/wyze69-sys/speccouncil/blob/master/internal/provider/cline/cline.go): `internal/provider/cline/cline.go`
- [Scripted provider](https://github.com/wyze69-sys/speccouncil/blob/master/internal/provider/fake/fake.go): `internal/provider/fake/fake.go`
- [Requirements review](https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go): `internal/review/runner.go`
- [Architecture review](https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go): `internal/review/runner.go`
- [QA review](https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go): `internal/review/runner.go`
- [Security review](https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/runner.go): `internal/review/runner.go`

### Persistence and workers

- [Review store](https://github.com/wyze69-sys/speccouncil/blob/master/internal/storage/sqlite/store.go): `internal/storage/sqlite/store.go`
- [Job preparation](https://github.com/wyze69-sys/speccouncil/blob/master/internal/storage/sqlite/prepare.go): `internal/storage/sqlite/prepare.go`
- [Worker supervision](https://github.com/wyze69-sys/speccouncil/blob/master/internal/worker/supervise.go): `internal/worker/supervise.go`
- [Role dispatch](https://github.com/wyze69-sys/speccouncil/blob/master/internal/worker/dispatch.go): `internal/worker/dispatch.go`
- [Result publication](https://github.com/wyze69-sys/speccouncil/blob/master/internal/storage/sqlite/publish.go): `internal/storage/sqlite/publish.go`

### Reporting

- [Report composition](https://github.com/wyze69-sys/speccouncil/blob/master/internal/review/composer.go): `internal/review/composer.go`
- [Report and status reads](https://github.com/wyze69-sys/speccouncil/blob/master/internal/storage/sqlite/read.go): `internal/storage/sqlite/read.go`

### Other components

- **Design submitter**
- **Cline service**

## Connections

- Design submitter → HTTP API: submits design (evidence: `README.md`)
- HTTP API → Review store: submits review job (evidence: `internal/api/server.go`)
- Snapshot input → Document ingestion: parses snapshot (evidence: `internal/api/snapshot_provider.go`)
- Document ingestion → Frozen evidence: freezes evidence
- Review store → Job preparation: prepares job (evidence: `internal/storage/sqlite/prepare.go`)
- Frozen evidence → Role runner: supplies shared snapshot (evidence: `README.md`)
- Worker supervision → Role dispatch: coordinates work
- Role dispatch → Role runner: runs roles
- Role runner → Prompt assembly: assembles prompts (evidence: `internal/review/runner.go`)
- Role runner → Provider boundary: calls provider (evidence: `internal/review/runner.go`)
- Role runner → Finding validation: validates responses (evidence: `README.md`)
- Provider boundary → Cline adapter: implemented by (evidence: `internal/provider/cline/cline.go`)
- Provider boundary → Scripted provider: implemented by (evidence: `internal/provider/fake/fake.go`)
- Cline adapter → Cline service: sends model request (evidence: `internal/provider/cline/cline.go`)
- Role runner → Requirements review: reviews requirements (evidence: `README.md`)
- Role runner → Architecture review: reviews architecture (evidence: `README.md`)
- Role runner → QA review: reviews testability (evidence: `README.md`)
- Role runner → Security review: reviews security (evidence: `README.md`)
- Finding validation → Result publication: accepts cited findings (evidence: `README.md`)
- Result publication → Review store: persists results (evidence: `README.md`)
- Role runner → Report composition: composes deterministic report
- Review store → Report and status reads: reads stored results (evidence: `internal/storage/sqlite/read.go`)
- Report and status reads → HTTP API: serves report (evidence: `README.md`)
