TrueCourse: a tool to find and prevent architectural debt in JavaScript and TypeScript projects
TrueCourse inspects JavaScript/TypeScript codebases for architectural debt and bugs, combining AST rules with LLM reviews to visually map cross-service traces.
Why TrueCourse matters now: AI coding speeds up development but hides architectural debt
The rise of AI-assisted coding—large language models that scaffold services, generate modules, and wire endpoints—has accelerated feature delivery. But this velocity comes with a hidden cost: architectural debt accumulating beneath the surface. TrueCourse is an open-source analysis tool that targets that cost by surfacing structural and semantic problems across JavaScript and TypeScript repositories. It looks for the kinds of violations that usually escape unit tests and conventional linters: circular dependencies, layer breaches, overgrown “god” modules, dead code, and cross-service coupling. For teams that integrate AI agents into their workflows, TrueCourse aims to be a system-level guardrail that makes architecture visible and actionable.
What TrueCourse detects and why those issues matter
TrueCourse scans a repository to identify architectural violations and deeper code-intelligence issues that degrade maintainability, performance, and security over time.
- Architectural violations: circular imports that create runtime fragility, modules that breach intended layering (for example, data-access code invoking API-layer logic), monolithic modules with excessive public surface area, and tightly coupled services that prevent safe refactoring.
- Semantic defects: empty catch blocks that mask failures, shared mutable state patterns that lead to race conditions, functions whose names are misleading relative to what they do, and security anti-patterns like weak token generation or unsafe use of dynamic evaluation.
- Cross-service flow analysis: automatic tracing of request and event flows across service boundaries, visualized end-to-end so developers can follow a request path from HTTP ingress to database writes and downstream consumers.
- Database and ORM checks: detection of common ORMs (Prisma, TypeORM, Drizzle, etc.), generation of entity-relationship diagrams, and heuristics for missing indexes or risky schema patterns that can slow queries or cause correctness issues.
Why these checks matter: architectural faults usually don’t fail CI gates. They accumulate as code is added, generating more coupling and friction for future change. When AI agents rapidly produce code without a consistent architectural intent, those problems multiply. By flagging them early, TrueCourse helps teams keep large codebases navigable and safer to evolve.
How TrueCourse performs analysis
TrueCourse combines deterministic static analysis with AI-assisted semantic review to provide both precision and contextual insight.
- AST-driven rules: The engine parses the codebase into abstract syntax trees and runs a suite of deterministic checks. These rules reliably identify structural patterns such as import cycles, layer-violation imports (e.g., UI depending on data-layer modules), and modules exceeding configurable size or export counts.
- Flow and call-graph generation: The analyzer computes inter-module call graphs and synthesizes cross-file traces. That graph information is what enables end-to-end visuals and helps trace the reach of a risky change.
- LLM-enhanced review: For issues that require semantic interpretation—misnamed functions, suspicious error handling, or complex race conditions—TrueCourse can call a language model to produce a human-readable explanation and remediation suggestions. The system supports configurable LLM providers and works with a built-in Claude Code option that requires no external API key.
- Persistent analysis store: On first run the tool creates a local lightweight database to cache results and enable features like historical diffs and the ability to compare successive analyses without re-parsing the entire repository.
Together, these layers let TrueCourse detect low-level syntax problems and higher-level architectural concerns that only emerge when you view the system as a network of services and data flows.
TrueCourse interfaces: visual exploration and machine-readable output
One of TrueCourse’s design premises is that architecture work is best served by both human-friendly visuals and machine-friendly outputs.
- Web UI for developers: The web interface renders interactive dependency graphs where nodes represent modules or services and edges show call or import relationships. Clicking a node shows its violations, inline markers in source snippets, and contextual trace paths. The UI also includes analytics that summarize hotspots and change-driven trends, offering a visual way to explore technical debt and investigate incident paths.
- CLI for automation and agents: The command-line interface is designed for integration into CI pipelines and AI coding agents. It emits structured analysis results, enabling automation workflows to ingest violations and either block merges, post PR comments, or trigger targeted remediation actions. The CLI is optimized for fast invocations and scriptability so that agents can incorporate architecture checks into automated pull-request cycles.
Both interfaces rely on the same underlying analysis engine and shared database, ensuring consistency between what a human reviewer sees and what an automation pipeline enforces.
Diff mode: pre-commit architecture checks that focus reviews
TrueCourse includes a diff mode that compares the current working tree against the last stored analysis and highlights only the changes that introduce or resolve violations. This is particularly valuable as a pre-commit or pre-merge check.
- How diff mode helps: Instead of re-reporting the entire universe of pre-existing issues, diff mode dims unchanged graph nodes and emphasizes nodes and edges affected by the current change. Developers see exactly which architecture constraints their patch touches and which violations might be newly introduced.
- Practical workflow: Run the command (for example, npx truecourse analyze –diff) locally, before committing or in a CI step. The tool will annotate the web UI and produce structured output for automation agents. This reduces noise and focuses remediation effort on the incremental risk from each change.
Diff-based enforcement turns architecture checks into a low-friction safety net: small, focused feedback that fits into iterative development.
Developer workflows and use cases
TrueCourse is relevant at multiple stages of a software lifecycle and across different team roles.
- Individual developers: Run quick local analyses to understand module responsibilities, discover dead modules, and see how a proposed change ripples through the system.
- Code reviewers: Use the dependency graph and inline violations to scope reviews beyond the file-level diffs and evaluate system-level impact.
- CI/CD pipelines: Tighten release gates by failing merges that introduce new high-severity architectural violations. Use structured CLI output to add comments on pull requests.
- AI agents and automation: Pair TrueCourse with code-generation agents so that generated code is automatically analyzed and annotated; agents can then propose refactors that align with architecture rules.
- Architects and engineering managers: Track architectural hotspots over time and prioritize rewrites or refactors based on which modules are most connected or most frequently changed.
These workflows help teams keep technical debt visible and actionable without slowing down development velocity.
Technical architecture and integration details
Under the hood, TrueCourse is architected to be self-contained and easy to adopt.
- Local server and embedded storage: On its first execution it spins up a local server and an embedded Postgres instance to persist analyses, traces, and configuration without requiring Docker or cloud infrastructure.
- Pluggable LLM support: While its default ship includes a no-key Claude Code option for convenience, teams can configure OpenAI, Anthropic, or other supported LLM providers via API keys to control costs and provider selection.
- Extensible detection rules: The deterministic AST checks can be extended. Future work includes a rule-generation pipeline so teams can codify their architecture constraints and share them as reusable rule sets.
- ORM and database analysis: TrueCourse recognizes common TypeScript/JavaScript ORMs and synthesizes ER diagrams and index heuristics. This helps map data-access patterns into the overall service graph.
- Output formats: The CLI emits structured JSON suitable for CI parsers and agent consumption, while the web UI provides an interactive exploration layer. That duality makes it straightforward to integrate with reporting systems, ticket trackers, or remediation bots.
These choices aim to minimize onboarding friction while still providing the observability necessary to manage complex systems.
Security, privacy, and operational concerns
A tool that analyzes source code raises practical questions about security and data handling; TrueCourse addresses these with defaults and design trade-offs.
- Local-first operation: By default TrueCourse runs locally, with analysis data stored in an embedded database on the developer’s machine or within CI runners. That reduces the need to send proprietary source code to external services.
- LLM usage controls: Teams that supply external LLM API keys retain the choice of provider and can enforce privacy policies accordingly. Sensitive code can be excluded from LLM review via configuration.
- Configurable scanning scope: Repositories can be configured to include or ignore folders, generated code, or vendor dependencies to limit analysis to production-relevant source.
- Audit trail and diffs: Persisted analyses mean teams can audit when violations appeared and correlate them to commits, making remediation accountable and traceable.
For organizations with stricter compliance requirements, local execution and careful LLM configuration allow TrueCourse to be part of a secure toolchain rather than a data-exfiltration risk.
Open source model and contribution pathways
TrueCourse is released under an MIT license and is intentionally early-stage. That model fosters community contribution and rapid iteration.
- Contribution focus: The project has labeled newcomer-friendly issues, a priority for expanding language support (Python is on the roadmap), and plans for customizable rule generation. Contributors can add AST rules, improve ORM detection, or help harden the UI and diff engine.
- Community value: Open-source stewardship makes it easier for teams to adapt the tool to their architecture, share rule sets, and build integrations into broader developer tooling ecosystems such as CI, code review bots, and changelog systems.
- Governance and stewardship: For long-term viability, an open governance model and maintainers committed to reviewing incoming patches will be important. Community engagement and real-world usage across diverse codebases will shape where the project invests next.
By remaining open, TrueCourse invites real-world feedback from teams wrestling with architectural debt, particularly in environments increasingly populated with AI-generated code.
Broader implications for the software industry and developer practices
TrueCourse is symptomatic of a larger shift: the tooling ecosystem must evolve from file-level hygiene to system-level observability as AI accelerates code generation. Several industry implications follow.
- Architectural governance at scale: As more services are generated or modified by automated agents, organizations will need machine-enforceable architecture policies to prevent erosion of modular boundaries and to preserve system mental models.
- Shift in code review focus: Reviewers will move from checking line-level correctness to validating design intent and system impact. Tools that surface cross-cutting concerns will become essential for meaningful reviews.
- DevOps and SRE interactions: Architecture issues such as missing indexes or inefficient cross-service flows have operational costs. Integrating architecture analysis into observability and incident workflows can shorten MTTR and guide capacity planning.
- Education and mental models: Teams will need shared, codified architecture principles—captured as rules that tools can check—to avoid divergence in design practices across AI-driven contributions.
- Market for architectural tooling: Expect a growth in tools that combine static analysis, runtime telemetry, and AI to build a continuous feedback loop between design intent, generated code, and live behavior.
TrueCourse demonstrates a pragmatic approach to these trends: treat architecture as first-class observable data, and give both humans and agents the signals required to keep systems coherent.
When and how to adopt TrueCourse in your stack
TrueCourse targets teams that maintain server-side JavaScript/TypeScript applications or microservice architectures and those experimenting with AI-assisted coding.
- Who should try it: Backend and full-stack engineers, architects, and teams adopting AI code generation—especially organizations that care about long-term maintainability across multiple services.
- When to integrate: Add TrueCourse early in a repo’s lifecycle to establish baselines and start tracking architectural hotspots. It’s also valuable to add into CI for incremental enforcement once a baseline is acceptable.
- How to start: Install with a single command line invocation (for example, using npx) to run an initial analysis and open the visual UI. Configure the LLM provider if you want semantic reviews, or rely on the included no-key option for lightweight use.
- Practical guidance: Begin with non-blocking detection to build familiarity; use diff mode to prioritize changes, and then progressively raise enforcement levels for new violations that breach your team’s architecture standards.
Adopting architecture-aware analysis should be incremental—start with visibility, iterate on rules, and only then move to policy enforcement.
Getting involved and where to find TrueCourse
TrueCourse is published as an open-source project with a public repository and an npm package. The project encourages experimentation, issue reporting, and contributions to expand its language and rule coverage. Developers can explore a live demo, install the package locally, and review roadmap issues labeled for newcomers to begin contributing.
TrueCourse’s early-stage status means real-world feedback from a variety of teams will influence its priorities—especially for enhancing Python support, rule customization, and richer database analysis.
Looking forward, tools like TrueCourse will be part of a new layer in the developer toolkit that treats architecture as observable, testable, and automatable. As code generation becomes more common, maintaining clear module boundaries, enforcing data-layer contracts, and tracing cross-service flows will be essential to sustaining rapid delivery without sacrificing maintainability. TrueCourse’s blend of deterministic AST checks, call-graph visualization, and optional LLM insight points to a pragmatic middle path: use automation to accelerate development, and use architecture-aware analysis to keep the whole system coherent and safe.
