# theharborproject/lantern architecture

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

- Interactive diagram: https://gitdiagram.com/theharborproject/lantern
- Repository: https://github.com/theharborproject/lantern

## Overview

Lantern is a TypeScript CLI and reusable API for discovering web components, planning component states, and auditing accessibility in a real browser. The principal flow is project configuration → component scan and accessibility projections → survey planning and execution → normalized checks and a SurveyRun result, optionally saved in project-scoped history. The README also documents interactive selection and history commands. Edges reflect README statements and visible source-index references; several CLI and runtime details are unsampled, so uncertain links are omitted.

Main entry points: [`src/survey/run-survey.ts`](https://github.com/theharborproject/lantern/blob/main/src/survey/run-survey.ts) (Survey workflow), [`src/scan/scan-service.ts`](https://github.com/theharborproject/lantern/blob/main/src/scan/scan-service.ts) (Scan orchestration), [`src/api/service.ts`](https://github.com/theharborproject/lantern/blob/main/src/api/service.ts) (Programmatic API), [`src/cli/commands`](https://github.com/theharborproject/lantern/tree/main/src/cli/commands) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI commands"]
  node_api["Programmatic API<br/>[service.ts]"]
end

subgraph group_project["Project setup"]
  node_config["Config resolution"]
  node_init["Project initialization<br/>[init-project.ts]"]
end

subgraph group_discovery["Discovery and planning"]
  node_scan["Scan orchestration<br/>[scan-service.ts]"]
  node_component_scan["Component analysis"]
  node_projections["Scan projections"]
  node_state_plan["State planning"]
  node_interactive["Interactive selection"]
end

subgraph group_audit["Audit execution"]
  node_survey["Survey workflow<br/>[run-survey.ts]"]
  node_lint_targets["Target resolution"]
  node_report["Check planning and report"]
  node_engines["Audit engines"]
  node_runtime["Component runtime<br/>[runtime-session.ts]"]
end

subgraph group_results["Results and history"]
  node_run_model["Survey run model<br/>[survey-run.ts]"]
  node_history[("Survey history<br/>[service.ts]")]
  node_renderer["Survey rendering"]
end

node_user(("CLI user"))
node_api_user(("API consumer"))
node_browser["Playwright browser"]

node_user -->|"runs commands"| node_cli
node_api_user -->|"calls API"| node_api
node_cli -->|"initializes project"| node_init
node_cli -->|"runs survey"| node_survey
node_api -->|"resolves config"| node_config
node_api -->|"scans project"| node_scan
node_api -->|"executes survey"| node_survey
node_init -->|"creates config"| node_config
node_scan -->|"scans sources"| node_component_scan
node_scan -->|"writes projections"| node_projections
node_scan -->|"reuses cached model"| node_component_scan
node_survey -->|"gets scan"| node_scan
node_survey -->|"resolves targets"| node_lint_targets
node_survey -->|"plans states"| node_state_plan
node_survey -->|"builds report"| node_report
node_lint_targets -->|"refreshes scan"| node_scan
node_report -->|"plans and executes checks"| node_engines
node_report -->|"creates runtime session"| node_runtime
node_engines -.->|"uses rendered session"| node_runtime
node_runtime -.->|"drives browser"| node_browser
node_survey -->|"produces run"| node_run_model
node_survey -.->|"persists run"| node_history
node_api -->|"renders run"| node_renderer
node_history -->|"validates stored runs"| node_run_model

click node_cli "https://github.com/theharborproject/lantern/tree/main/src/cli/commands"
click node_api "https://github.com/theharborproject/lantern/blob/main/src/api/service.ts"
click node_config "https://github.com/theharborproject/lantern/tree/main/src/config"
click node_init "https://github.com/theharborproject/lantern/blob/main/src/init/init-project.ts"
click node_scan "https://github.com/theharborproject/lantern/blob/main/src/scan/scan-service.ts"
click node_component_scan "https://github.com/theharborproject/lantern/blob/main/src/component-scan/run-component-scan.ts"
click node_projections "https://github.com/theharborproject/lantern/tree/main/src/component-scan"
click node_state_plan "https://github.com/theharborproject/lantern/blob/main/src/state-planning/plan-component-state.ts"
click node_interactive "https://github.com/theharborproject/lantern/tree/main/src/interactive"
click node_survey "https://github.com/theharborproject/lantern/blob/main/src/survey/run-survey.ts"
click node_lint_targets "https://github.com/theharborproject/lantern/blob/main/src/lint/resolve-lint-targets.ts"
click node_report "https://github.com/theharborproject/lantern/blob/main/src/lint/build-lint-report.ts"
click node_engines "https://github.com/theharborproject/lantern/tree/main/src/engines"
click node_runtime "https://github.com/theharborproject/lantern/blob/main/src/component-runtime/runtime-session.ts"
click node_run_model "https://github.com/theharborproject/lantern/blob/main/src/survey/schema/survey-run.ts"
click node_history "https://github.com/theharborproject/lantern/blob/main/src/history/service.ts"
click node_renderer "https://github.com/theharborproject/lantern/blob/main/src/survey/render-survey-run.ts"

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_api,node_user,node_browser toneBlue
class node_config,node_init toneAmber
class node_scan,node_component_scan,node_projections,node_state_plan,node_interactive,node_api_user toneMint
class node_survey,node_lint_targets,node_report,node_engines,node_runtime toneRose
class node_run_model,node_history,node_renderer toneIndigo
```

## Components

### Entry points

- [CLI commands](https://github.com/theharborproject/lantern/tree/main/src/cli/commands): `src/cli/commands`
- [Programmatic API](https://github.com/theharborproject/lantern/blob/main/src/api/service.ts): `src/api/service.ts`

### Project setup

- [Config resolution](https://github.com/theharborproject/lantern/tree/main/src/config): `src/config`
- [Project initialization](https://github.com/theharborproject/lantern/blob/main/src/init/init-project.ts): `src/init/init-project.ts`

### Discovery and planning

- [Scan orchestration](https://github.com/theharborproject/lantern/blob/main/src/scan/scan-service.ts): `src/scan/scan-service.ts`
- [Component analysis](https://github.com/theharborproject/lantern/blob/main/src/component-scan/run-component-scan.ts): `src/component-scan/run-component-scan.ts`
- [Scan projections](https://github.com/theharborproject/lantern/tree/main/src/component-scan): `src/component-scan`
- [State planning](https://github.com/theharborproject/lantern/blob/main/src/state-planning/plan-component-state.ts): `src/state-planning/plan-component-state.ts`
- [Interactive selection](https://github.com/theharborproject/lantern/tree/main/src/interactive): `src/interactive`

### Audit execution

- [Survey workflow](https://github.com/theharborproject/lantern/blob/main/src/survey/run-survey.ts): `src/survey/run-survey.ts`
- [Target resolution](https://github.com/theharborproject/lantern/blob/main/src/lint/resolve-lint-targets.ts): `src/lint/resolve-lint-targets.ts`
- [Check planning and report](https://github.com/theharborproject/lantern/blob/main/src/lint/build-lint-report.ts): `src/lint/build-lint-report.ts`
- [Audit engines](https://github.com/theharborproject/lantern/tree/main/src/engines): `src/engines`
- [Component runtime](https://github.com/theharborproject/lantern/blob/main/src/component-runtime/runtime-session.ts): `src/component-runtime/runtime-session.ts`

### Results and history

- [Survey run model](https://github.com/theharborproject/lantern/blob/main/src/survey/schema/survey-run.ts): `src/survey/schema/survey-run.ts`
- [Survey history](https://github.com/theharborproject/lantern/blob/main/src/history/service.ts): `src/history/service.ts`
- [Survey rendering](https://github.com/theharborproject/lantern/blob/main/src/survey/render-survey-run.ts): `src/survey/render-survey-run.ts`

### Other components

- **CLI user**
- **API consumer**
- **Playwright browser**

## Connections

- CLI user → CLI commands: runs commands (evidence: `README.md`)
- API consumer → Programmatic API: calls API (evidence: `README.md`)
- CLI commands → Project initialization: initializes project
- CLI commands → Survey workflow: runs survey
- Programmatic API → Config resolution: resolves config (evidence: `src/api/service.ts`)
- Programmatic API → Scan orchestration: scans project (evidence: `src/api/service.ts`)
- Programmatic API → Survey workflow: executes survey (evidence: `src/api/service.ts`)
- Project initialization → Config resolution: creates config (evidence: `src/init/init-project.ts`)
- Scan orchestration → Component analysis: scans sources (evidence: `src/scan/scan-service.ts`)
- Scan orchestration → Scan projections: writes projections (evidence: `src/scan/scan-service.ts`)
- Scan orchestration → Component analysis: reuses cached model (evidence: `src/scan/scan-service.ts`)
- Survey workflow → Scan orchestration: gets scan (evidence: `src/survey/run-survey.ts`)
- Survey workflow → Target resolution: resolves targets (evidence: `src/survey/run-survey.ts`)
- Survey workflow → State planning: plans states (evidence: `src/survey/run-survey.ts`)
- Survey workflow → Check planning and report: builds report (evidence: `src/survey/run-survey.ts`)
- Target resolution → Scan orchestration: refreshes scan (evidence: `src/lint/resolve-lint-targets.ts`)
- Check planning and report → Audit engines: plans and executes checks (evidence: `src/lint/build-lint-report.ts`)
- Check planning and report → Component runtime: creates runtime session (evidence: `src/lint/build-lint-report.ts`)
- Audit engines → Component runtime: uses rendered session
- Component runtime → Playwright browser: drives browser (evidence: `README.md`)
- Survey workflow → Survey run model: produces run (evidence: `src/survey/run-survey.ts`)
- Survey workflow → Survey history: persists run (evidence: `README.md`)
- Programmatic API → Survey rendering: renders run (evidence: `src/public-api.ts`)
- Survey history → Survey run model: validates stored runs (evidence: `src/history/service.ts`)
