# truecourse-ai/truecourse architecture

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

- Interactive diagram: https://gitdiagram.com/truecourse-ai/truecourse
- Repository: https://github.com/truecourse-ai/truecourse

## Overview

1. **Repository shape**
   This is a monorepo centered on a TypeScript-based static analysis platform. The main runtime pieces are:
   - `packages/analyzer`: language-aware analysis engine
   - `packages/core`: orchestration, persistence, CLI/service logic
   - `tools/cli`: end-user command-line entrypoint
   - `apps/dashboard`: local web dashboard with server + React client
   - `apps/landing`: marketing site
   - `packages/shared`: cross-package type/schema contract

2. **Primary product boundary**
   The core product is not a hosted SaaS backend. It analyzes a local Git repo and writes state into a repo-local `.truecourse/` directory as JSON. That directory is the system’s persistence boundary: baseline snapshots, diff results, history, config, hook policy, and UI state live there rather than in a database.

3. **Analysis pipeline**
   The analyzer package is the engine that scans source files, builds structural models, and emits findings. Its pipeline includes:
   - file discovery and parsing
   - language-specific extractors for JavaScript/TypeScript and Python
   - graph construction for modules, services, dependencies, flows, and database/schema metadata
   - rule execution across categories such as architecture, bugs, security, performance, reliability, database, code quality, and style

4. **Rule system**
   Rules are organized by domain and by execution mode:
   - deterministic rules: AST/tree-sitter-style visitors with no external calls
   - LLM rules: semantic checks that use the Claude Code CLI as an external process
   - shared checker layers in `packages/analyzer/src/rules/*/checker.ts` and `llm.ts`
   The analyzer also has dedicated support for architecture, bugs, security, performance, reliability, database, and style visitors, with separate JS/TS and Python implementations where needed.

5. **Graph and semantic models**
   A major output of the analyzer is a repo graph, not just a list of violations. The graph represents modules, services, layers, methods, databases, and flows. This is what powers the architecture views in the dashboard and the “dead module / circular dependency / layer violation” style findings.

6. **Core orchestration layer**
   `packages/core` sits between the analyzer and all user-facing commands. It owns:
   - analysis execution and persistence
   - diff analysis against the committed baseline
   - graph and flow services
   - violation lifecycle, query, and pipeline services
   - rule registry / enable-disable state
   - telemetry and usage reporting
   - LLM provider abstraction and context routing
   This package is the main boundary where analysis results become durable repo state and CLI/dashboard consumables.

7. **CLI and command surface**
   `tools/cli` is the user entrypoint. It exposes commands for:
   - analyze/list/diff
   - rule management
   - dashboard start/stop/status/logs/uninstall
   - hook installation
   - telemetry and add/register flows
   It also includes platform-specific service management for background dashboard mode on Linux, macOS, and Windows. In architecture terms, it is a thin shell over `packages/core` plus dashboard/service bootstrapping.

8. **Dashboard backend**
   `apps/dashboard/server` is a local HTTP + socket service. It exposes route modules for:
   - analyses, analytics, databases, files, flows, graph, repos, rules, violations
   - websocket/socket handlers for live updates
   - middleware for error handling and project context
   There is also a watcher service that likely tracks filesystem changes and pushes refresh events over the socket. This server is the API boundary for the web UI.

9. **Dashboard frontend**
   `apps/dashboard/client` is a Vite/React UI that visualizes the analysis output. It is organized by feature panels:
   - repo selection and repo list
   - graph canvas and graph controls
   - file tree and code viewer
   - violations, rules, analyses, analytics, flows, schema/database views
   The UI reads from the dashboard server through typed client hooks and API helpers, and it is focused on exploration/triage rather than analysis itself.

10. **Shared contracts**
   `packages/shared` defines the wire format and shared domain types for analyses, analytics, violations, flows, database entities, rules, and graphs. This package is the compatibility boundary between core, server, and client, keeping the dashboard and CLI aligned on data shape.

11. **External process dependency**
   LLM-powered rules depend on the Claude Code CLI being available on PATH. That external binary is invoked by the core’s LLM service layer, with environment-driven configuration for binary path, model, timeout, retries, and concurrency. Deterministic analysis still works without it.

12. **Inputs and repo context**
   The system is designed around the current Git repository as the unit of analysis. It respects Git ignore rules and optional `.truecourseignore`, uses the committed baseline in `.truecourse/LATEST.json` for diff mode and hooks, and supports worktrees/fresh clones by treating the repo itself as the source of truth.

13. **Testing and fixtures**
   The repo has extensive tests around analyzer behavior, core orchestration, CLI flows, and dashboard routes. The fixtures under `tests/fixtures/*` are especially important: they model positive and negative JS and Python repos, and they drive expected-graph comparisons. This suggests architecture validation is heavily snapshot/fixture-based.

14. **Auxiliary apps and release flow**
   `apps/landing` is a separate marketing frontend with its own small API for waitlist capture, while GitHub Actions handle test and publish workflows. These are peripheral to the analysis architecture but show the repo is packaged and distributed as a tool, not just a library.

Main entry points: [`packages/core/src/commands/analyze-core.ts`](https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/commands/analyze-core.ts) (Core Commands), [`packages/analyzer/src/index.ts`](https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/index.ts) (Analyzer), [`packages/analyzer/src/rule-engine.ts`](https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/rule-engine.ts) (Rules), [`apps/dashboard/server/src/app.ts`](https://github.com/truecourse-ai/truecourse/blob/main/apps/dashboard/server/src/app.ts) (Dashboard Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Product Boundary"]
  node_truecourse_store[(".truecourse<br/>repo state store")]
end

subgraph group_analysis["Analysis Engine"]
  node_analyzer_pipeline["Analyzer<br/>static analysis engine<br/>[index.ts]"]
  node_file_discovery["Discovery<br/>repo scanner<br/>[file-discovery.ts]"]
  node_parsers_extractors["Parsing<br/>language frontends<br/>[parser.ts]"]
  node_graphs_models["Graph Model<br/>repo graph builder<br/>[analysis-graph.ts]"]
  node_rules_engine["Rules<br/>deterministic + LLM<br/>[rule-engine.ts]"]
  node_analyzer_rules_js["JS/TS Rules<br/>visitor suites<br/>[index.ts]"]
  node_analyzer_rules_py["Python Rules<br/>visitor suites<br/>[index.ts]"]
  node_llm_cli["Claude CLI<br/>external process"]
end

subgraph group_orchestration["Core Orchestration"]
  node_core_commands["Core Commands<br/>execution entrypoints<br/>[analyze-core.ts]"]
  node_analysis_persistence["Persistence<br/>state writer"]
  node_graph_service["Graph Service<br/>query service<br/>[graph.service.ts]"]
  node_flow_service["Flow Service<br/>query service<br/>[flow.service.ts]"]
  node_violations_services["Violations<br/>lifecycle + query"]
  node_llm_service["LLM Service<br/>provider abstraction<br/>[provider.ts]"]
end

subgraph group_ui["User Interfaces"]
  node_cli_entry["CLI<br/>user shell<br/>[index.ts]"]
  node_dashboard_server["Dashboard Server<br/>local api server<br/>[app.ts]"]
  node_dashboard_client["Dashboard UI<br/>react client<br/>[App.tsx]"]
end

subgraph group_contracts["Shared Contracts"]
  node_shared_contracts["Shared Types<br/>schemas + contracts<br/>[index.ts]"]
end

node_cli_entry -->|"invokes"| node_core_commands
node_core_commands -->|"runs"| node_analyzer_pipeline
node_analyzer_pipeline -->|"discovers"| node_file_discovery
node_analyzer_pipeline -->|"parses"| node_parsers_extractors
node_analyzer_pipeline -->|"builds"| node_graphs_models
node_analyzer_pipeline -->|"executes"| node_rules_engine
node_rules_engine -->|"js/ts"| node_analyzer_rules_js
node_rules_engine -->|"python"| node_analyzer_rules_py
node_rules_engine -.->|"semantic checks"| node_llm_cli
node_core_commands -->|"persists"| node_analysis_persistence
node_analysis_persistence -->|"writes"| node_truecourse_store
node_core_commands -->|"exposes"| node_graph_service
node_core_commands -->|"exposes"| node_flow_service
node_core_commands -->|"exposes"| node_violations_services
node_core_commands -->|"routes"| node_llm_service
node_llm_service -.->|"uses"| node_llm_cli
node_cli_entry -->|"starts/stops"| node_dashboard_server
node_dashboard_server -->|"reads"| node_core_commands
node_dashboard_server -->|"types"| node_shared_contracts
node_dashboard_client -->|"calls"| node_dashboard_server
node_dashboard_client -->|"types"| node_shared_contracts
node_core_commands -->|"serializes"| node_shared_contracts
node_analyzer_pipeline -->|"emits"| node_shared_contracts

click node_analyzer_pipeline "https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/index.ts"
click node_file_discovery "https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/file-discovery.ts"
click node_parsers_extractors "https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/parser.ts"
click node_graphs_models "https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/analysis-graph.ts"
click node_rules_engine "https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/rule-engine.ts"
click node_analyzer_rules_js "https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/rules/architecture/visitors/javascript/index.ts"
click node_analyzer_rules_py "https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/rules/architecture/visitors/python/index.ts"
click node_core_commands "https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/commands/analyze-core.ts"
click node_analysis_persistence "https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/analysis-persistence.service.ts"
click node_graph_service "https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/graph.service.ts"
click node_flow_service "https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/flow.service.ts"
click node_violations_services "https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/violation.service.ts"
click node_llm_service "https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/llm/provider.ts"
click node_cli_entry "https://github.com/truecourse-ai/truecourse/blob/main/tools/cli/src/index.ts"
click node_dashboard_server "https://github.com/truecourse-ai/truecourse/blob/main/apps/dashboard/server/src/app.ts"
click node_dashboard_client "https://github.com/truecourse-ai/truecourse/blob/main/apps/dashboard/client/src/App.tsx"
click node_shared_contracts "https://github.com/truecourse-ai/truecourse/blob/main/packages/shared/src/index.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_truecourse_store toneBlue
class node_analyzer_pipeline,node_file_discovery,node_parsers_extractors,node_graphs_models,node_rules_engine,node_analyzer_rules_js,node_analyzer_rules_py,node_llm_cli toneAmber
class node_core_commands,node_analysis_persistence,node_graph_service,node_flow_service,node_violations_services,node_llm_service toneMint
class node_cli_entry,node_dashboard_server,node_dashboard_client toneRose
class node_shared_contracts toneIndigo
```

## Components

### Product Boundary

Local repo analysis state stored in .truecourse rather than a database.

- **.truecourse**: repo state store · Repo-local JSON persistence boundary for baselines, diffs, history, config, hooks, and UI state.

### Analysis Engine

Static analysis, graph building, and rule execution.

- [Analyzer](https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/index.ts): static analysis engine · Coordinates discovery, parsing, extraction, graph building, and rule execution. · `packages/analyzer/src/index.ts`
- [Discovery](https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/file-discovery.ts): repo scanner · Finds source files while respecting repo context and ignore rules. · `packages/analyzer/src/file-discovery.ts`
- [Parsing](https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/parser.ts): language frontends · Language-aware parsers, extractors, and helpers for JavaScript, TypeScript, and Python. · `packages/analyzer/src/parser.ts`
- [Graph Model](https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/analysis-graph.ts): repo graph builder · Builds modules, services, layers, dependencies, flows, and database/schema models. · `packages/analyzer/src/analysis-graph.ts`
- [Rules](https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/rule-engine.ts): deterministic + LLM · Runs domain rules across architecture, bugs, security, performance, reliability, database, code quality, and style. · `packages/analyzer/src/rule-engine.ts`
- [JS/TS Rules](https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/rules/architecture/visitors/javascript/index.ts): visitor suites · JavaScript and TypeScript rule visitors for the main deterministic rule domains. · `packages/analyzer/src/rules/architecture/visitors/javascript/index.ts`
- [Python Rules](https://github.com/truecourse-ai/truecourse/blob/main/packages/analyzer/src/rules/architecture/visitors/python/index.ts): visitor suites · Python rule visitors mirrored across the same major rule domains. · `packages/analyzer/src/rules/architecture/visitors/python/index.ts`
- **Claude CLI**: external process · External Claude Code CLI invoked for semantic LLM-backed rules.

### Core Orchestration

Persistence, diffing, services, and command execution.

- [Core Commands](https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/commands/analyze-core.ts): execution entrypoints · Analyze, diff, and persistence command implementations between the CLI and services. · `packages/core/src/commands/analyze-core.ts`
- [Persistence](https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/analysis-persistence.service.ts): state writer · Writes analysis results and baseline snapshots into repo-local durable state. · `packages/core/src/services/analysis-persistence.service.ts`
- [Graph Service](https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/graph.service.ts): query service · Serves graph and module views derived from analyzer output. · `packages/core/src/services/graph.service.ts`
- [Flow Service](https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/flow.service.ts): query service · Produces and queries traced flows from analysis output. · `packages/core/src/services/flow.service.ts`
- [Violations](https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/violation.service.ts): lifecycle + query · Owns violation lifecycle, pipelines, and query surfaces for analysis results. · `packages/core/src/services/violation.service.ts`
- [LLM Service](https://github.com/truecourse-ai/truecourse/blob/main/packages/core/src/services/llm/provider.ts): provider abstraction · Context routing and provider abstraction for LLM-backed checks. · `packages/core/src/services/llm/provider.ts`

### User Interfaces

CLI and dashboard surfaces for operating and exploring analyses.

- [CLI](https://github.com/truecourse-ai/truecourse/blob/main/tools/cli/src/index.ts): user shell · End-user command surface for analyze, diff, rules, hooks, telemetry, and dashboard control. · `tools/cli/src/index.ts`
- [Dashboard Server](https://github.com/truecourse-ai/truecourse/blob/main/apps/dashboard/server/src/app.ts): local api server · HTTP, socket, middleware, and watcher layer for the local dashboard UI. · `apps/dashboard/server/src/app.ts`
- [Dashboard UI](https://github.com/truecourse-ai/truecourse/blob/main/apps/dashboard/client/src/App.tsx): react client · Exploration and triage interface for graphs, files, flows, violations, rules, analytics, and schema. · `apps/dashboard/client/src/App.tsx`

### Shared Contracts

Cross-package types and wire schemas.

- [Shared Types](https://github.com/truecourse-ai/truecourse/blob/main/packages/shared/src/index.ts): schemas + contracts · Shared analysis, analytics, violations, flows, database, rules, and graph types. · `packages/shared/src/index.ts`

## Connections

- CLI → Core Commands: invokes · CLI commands delegate execution to core orchestration.
- Core Commands → Analyzer: runs · Core launches repository analysis through the analyzer engine.
- Analyzer → Discovery: discovers · Analysis starts by scanning repo files.
- Analyzer → Parsing: parses · Files are parsed and normalized through language-specific frontends.
- Analyzer → Graph Model: builds · Structural and semantic graph models are produced from parsed code.
- Analyzer → Rules: executes · Rule suites run over the extracted models and syntax trees.
- Rules → JS/TS Rules: js/ts · JavaScript and TypeScript deterministic visitors.
- Rules → Python Rules: python · Python deterministic visitors.
- Rules → Claude CLI: semantic checks · LLM rules call out to the Claude Code CLI when enabled.
- Core Commands → Persistence: persists · Analysis results and baselines are written into repo-local state.
- Persistence → .truecourse: writes · Durable JSON state lives under .truecourse/ in the repository.
- Core Commands → Graph Service: exposes · Core exposes graph-derived queries for consumers.
- Core Commands → Flow Service: exposes · Core exposes flow-tracing queries for consumers.
- Core Commands → Violations: exposes · Violation lifecycle and query services are part of core.
- Core Commands → LLM Service: routes · Core routes LLM configuration and provider access.
- LLM Service → Claude CLI: uses · The provider abstraction shells out to the Claude CLI.
- CLI → Dashboard Server: starts/stops · CLI manages the local dashboard service lifecycle.
- Dashboard Server → Core Commands: reads · Server handlers consume core services and persisted analysis state.
- Dashboard Server → Shared Types: types · Server uses shared domain schemas for API payloads.
- Dashboard UI → Dashboard Server: calls · React UI fetches typed data and receives live updates from the server.
- Dashboard UI → Shared Types: types · Client aligns to the same shared analysis and UI data shapes.
- Core Commands → Shared Types: serializes · Core persists and returns shared domain objects.
- Analyzer → Shared Types: emits · Analyzer output conforms to shared graph, violation, and analytics contracts.