How truecourse-ai/truecourse works
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: analyze-core.ts Core Commands · index.ts Analyzer · rule-engine.ts Rules · app.ts Dashboard Server
Components 19
Product Boundary
Local repo analysis state stored in .truecourse rather than a database.
- .truecourse · Repo-local JSON persistence boundary for baselines, diffs, history, config, hooks, and UI state.
Analysis Engine
Static analysis, graph building, and rule execution.
- Analyzer · Coordinates discovery, parsing, extraction, graph building, and rule execution.
packages/analyzer/src/index.ts - Discovery · Finds source files while respecting repo context and ignore rules.
packages/analyzer/src/file-discovery.ts - Parsing · Language-aware parsers, extractors, and helpers for JavaScript, TypeScript, and Python.
packages/analyzer/src/parser.ts - Graph Model · Builds modules, services, layers, dependencies, flows, and database/schema models.
packages/analyzer/src/analysis-graph.ts - Rules · Runs domain rules across architecture, bugs, security, performance, reliability, database, code quality, and style.
packages/analyzer/src/rule-engine.ts - JS/TS Rules · JavaScript and TypeScript rule visitors for the main deterministic rule domains.
packages/analyzer/src/rules/architecture/visitors/javascript/index.ts - Python Rules · Python rule visitors mirrored across the same major rule domains.
packages/analyzer/src/rules/architecture/visitors/python/index.ts - Claude CLI · External Claude Code CLI invoked for semantic LLM-backed rules.
Core Orchestration
Persistence, diffing, services, and command execution.
- Core Commands · Analyze, diff, and persistence command implementations between the CLI and services.
packages/core/src/commands/analyze-core.ts - Persistence · Writes analysis results and baseline snapshots into repo-local durable state.
packages/core/src/services/analysis-persistence.service.ts - Graph Service · Serves graph and module views derived from analyzer output.
packages/core/src/services/graph.service.ts - Flow Service · Produces and queries traced flows from analysis output.
packages/core/src/services/flow.service.ts - Violations · Owns violation lifecycle, pipelines, and query surfaces for analysis results.
packages/core/src/services/violation.service.ts - LLM Service · 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 · End-user command surface for analyze, diff, rules, hooks, telemetry, and dashboard control.
tools/cli/src/index.ts - Dashboard Server · HTTP, socket, middleware, and watcher layer for the local dashboard UI.
apps/dashboard/server/src/app.ts - Dashboard UI · 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 · Shared analysis, analytics, violations, flows, database, rules, and graph types.
packages/shared/src/index.ts
Connections 23
- 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.