The Problem
Development teams struggle to maintain architectural integrity as codebases grow. Traditional linters catch syntax issues but miss architectural violations — circular dependencies that create build breakage, layer violations where lower layers call higher ones, and dead modules that accumulate unused code. These issues compound over time, making refactoring risky and onboarding difficult for new team members.
What This Does
TrueCourse is an AI-powered architecture analysis and code intelligence platform that detects the gaps traditional tools miss. The monorepo structure organizes work across apps/server (160 files — the backend service), apps/web (66 TSX files — the React frontend), and packages/analyzer (16 files — the core analysis engine).
The analysis engine in packages/analyzer/src/ performs static analysis through extractors for TypeScript, JavaScript, Python, and HTTP calls. The web UI at apps/web/src/ visualizes results through dependency graphs, violation cards, ER diagrams, and flow tracing. The CLI integrates with the same engine for automation workflows. Both interfaces share the analysis database — run analyze from an agent, review results in the UI.
The platform detects circular dependencies, layer violations (e.g., data layer calling API layer), god modules, dead modules, tight coupling, and database issues. Code intelligence rules review actual source for error handling patterns, race conditions, misleading names, dead code, security anti-patterns, and resource leaks. Inline code viewer markers show severity ranges and fix suggestions.
How To Use It
Setup: The repo uses a monorepo structure with npm. Key config files include apps/server/package.json, apps/web/package.json, package.json at root, and packages/analyzer/package.json. Docker is configured via docker-compose.yml and docker/ directory. CI/CD pipelines exist in .github/workflows/test.yml and .github/workflows/publish.yml.
Configuration: Environment configuration lives in apps/server/src/config/env.ts with supporting files apps/server/src/config/index.ts and apps/server/src/config/database.ts. The .env.example file at root provides template variables. Database migrations reside in apps/server/src/db/migrations/ with schema definition at apps/server/src/schema.ts.
Running it: The CLI entry point is apps/server/src/index.ts. The README indicates analysis can be triggered via the CLI, though specific invocation commands should be verified against the package scripts in the various package.json files. The web UI starts via Vite as configured in apps/web/vite.config.ts.
Real-World Use
A backend team receives a CI flag about a circular dependency between apps/server/src/routes/analysis.ts and apps/server/src/services/analysis-registry.ts. TrueCourse identifies the cycle, marks both files in the dependency graph, and suggests reordering imports to break the cycle. Simultaneously, the code intelligence rules flag apps/server/src/middleware/error.ts for a catch block that silently swallows errors — a semantic issue an AST linter would miss. The developer reviews both findings in the web UI, applies the fix suggestions, and re-runs analyze to confirm resolution.
Code Health & Issues
Low/Risk: Dependencies declared without a lockfile — apps/server/package.json has no package-lock.json or pnpm-lock.yaml, meaning installs are non-reproducible across environments. Med: Only 2 test files found across 200 total files — limited test coverage reduces confidence in refactoring safety, especially for the analysis pipeline in packages/analyzer/. Med: No lockfile combined with npm scripts in multiple package.json files creates potential version drift between development and CI environments. Low: Root package.json and apps/web/package.json exist but scripts and versions should be verified for consistency across the monorepo.
The repo has CI configured, a clear monorepo structure, and the analysis engine is functional — these are positive signals for a tool still establishing its operational patterns.
The Bottom Line
TrueCourse fills a genuine gap for teams needing architectural guardrails beyond what linters provide. The monorepo organization, dual CLI+UI interfaces, and AI-enhanced code intelligence show thoughtful design. The missing lockfile and sparse test coverage are practical risks to address before integrating into a production CI pipeline. Teams managing moderate-to-large codebases with complex layering will see the most value; smaller projects may find the overhead disproportionate to the benefit.