truecourse - Moses Yebei

The Problem

Large codebases that mix a web UI, service layer, and analysis engine quickly accumulate hidden architectural debt: circular imports, “god” modules, and duplicated scaffolding. Those issues make small changes ripple across many files, increase build times, and raise the risk of runtime failures that ordinary linters miss.

What This Does

truecourse ships three self‑contained projects:

apps/server – a TypeScript/Node API (see apps/server/src/index.ts) that exposes analysis results, runs LLM providers, and persists data via Prisma.
apps/web – a React UI built with Vite (apps/web/vite.config.ts) that visualises dependency graphs, code violations, and database ER diagrams.
tools/cli – a command‑line front‑end for automation (e.g. tools/cli/src/commands/service/platform.ts).

Shared utilities live in packages/ (e.g. packages/analyzer, packages/shared). The Docker compose file (docker-compose.yml) wires the API, UI, and a PostgreSQL instance together, so the whole platform can be started with a single container orchestrator command.

How It Is Wired

Execution begins in apps/server/src/index.ts (the main entry point). It creates the Express app, mounts routes (apps/server/src/routes/*.ts), and starts the HTTP server.

Routes → Services – each route handler delegates to a service module (e.g. apps/server/src/services/analysis-pipeline.service.ts).
Services → Analyzer – the pipeline calls packages/analyzer/src/index (33 outgoing imports, instability 1) to run the static‑analysis rules.
LLM Provider – apps/server/src/services/llm/provider.ts supplies the model used by the analyzer; it is also part of a reported import cycle with tools/cli/src/commands/service/platform.ts and apps/server/src/services/llm/prompts.ts.
Database – apps/server/src/config/database.ts (imported by 18 modules) creates a Prisma client used by many services (apps/server/src/services/*.service.ts).
Web UI – apps/web/src/App.tsx bootstraps the React app; API calls go through apps/web/src/lib/api.ts (fetchApi, getRepos, etc.), a hub called from nine other files.

The internal call graph shows a few high‑blast‑radius functions: cn (36 callers), fetchApi (33 callers), and eq (23 callers). The most connected module, packages/analyzer/src/index, imports 33 other internal modules but is not itself imported, indicating a one‑way “utility” layer that can become a bottleneck for change.

Circular dependencies (nine members) involve the LLM provider stack, increasing build‑time fragility. Oversized files (>800 LOC) such as apps/server/src/services/graph.service.ts and apps/server/src/routes/analysis.ts concentrate many responsibilities, making local edits risky.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/truecourse
cd truecourse

# 2. Install Node dependencies (pnpm is used in CI)
pnpm install   # falls back to npm if pnpm not available

# 3. Create a runtime env file from the example
cp .env.example .env   # edit .env with your DB credentials, AI keys, etc.

# 4. Start the full stack (API, UI, Postgres) via Docker
docker compose up --build   # runs apps/server, apps/web, and the DB

# 5. API is reachable at http://localhost:3000
#    UI at http://localhost:5173

If you prefer a local Node run, build the server with pnpm run build (defined in apps/server/package.json) and start it via node apps/server/dist/index.js after setting .env.

The CLI can be invoked directly:

pnpm exec truecourse analyze <path-to-repo>

(Exact command name is defined in tools/cli/package.json.)

Real‑World Use

A CI pipeline can run truecourse as a pre‑merge gate: the CLI analyses the PR’s changed files, emits JSON‑encoded violations, and the pipeline aborts on any high severity finding. The same analysis engine powers the UI, letting developers explore the dependency graph and drill into offending code directly from the browser.

Code Health & Issues

HIGH – Pin GitHub Action versions to commit SHAs (.github/workflows/*).
HIGH – Replace cors() wildcard with an explicit allow list (apps/server/src/index.ts).
MEDIUM – Declare least‑privilege GITHUB_TOKEN permissions (.github/workflows/test.yml).
MEDIUM – Enable Dependabot / Renovate for automated updates.
MEDIUM – Add a dependency‑vulnerability scan step in CI.
MEDIUM – Move large binary assets (assets/demo.gif, demo.mp4) to Git LFS or external storage.
MEDIUM – Set persist-credentials: false on checkout (.github/workflows/publish.yml).
LOW – Add timeout-minutes to workflow jobs.
LOW – Provide repository convention files (.editorconfig, .gitattributes, formatter config).

Measured static‑analysis findings (deterministic):

Import cycles – 9 modules (e.g., provider.ts, platform.ts, prompts.ts).
Oversized files – 8 files > 800 LOC, high change impact.
High branching density – 26 files with > 70 branch points (e.g., dependency-graph.ts).
Hub modules – database.ts, schema.ts, language-config.ts each imported by 18 modules.
Duplicated code blocks – 692 repeated 6‑line fragments across 89 files.
Deep nesting – 9 files with indentation depth 8 (e.g., SchemaPanel.tsx).
Empty catch blocks – found in test files.
TODO/FIXME markers – 8 occurrences in analyzer rules.

No critical or blocker findings were detected beyond the above.

The Bottom Line

truecourse delivers a functional analysis engine, a usable React UI, and a CLI that together expose architectural flaws most linters miss. The codebase is modular but suffers from a few large, highly coupled modules and several import cycles that raise maintenance risk. With the listed health‑audit fixes and a refactor of the oversized services, the platform is ready for production use, especially in environments that need automated architecture validation in CI pipelines.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

398 files

TypeScript208
TSX66
JSON36
Python36
SQL13
Markdown10

ReactFlaskDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["apps 127 modules"] g1["packages 66 modules"] g2["tests 40 modules"] g3["tools 16 modules"] g4["scripts 3 modules"] g2 -->|87| g1 g2 -->|19| g0 g2 -->|5| g3

Module dependencies

The 10 most depended-upon modules of 253, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_s_server_src_config_database["database"] n1_apps_server_src_db_schema["schema"] n2_analyzer_src_language_config["language-config"] n3_es_shared_src_types_analysis["analysis"] n4__analyzer_src_file_discovery["file-discovery"] n5__server_src_middleware_error["error"] n6_packages_analyzer_src_parser["parser"] n7_s_analyzer_src_file_analyzer["file-analyzer"] n8_nalyzer_src_dependency_graph["dependency-graph"] n9_rc_services_analyzer_service["analyzer.service"] n0_s_server_src_config_database --> n1_apps_server_src_db_schema n8_nalyzer_src_dependency_graph --> n2_analyzer_src_language_config n7_s_analyzer_src_file_analyzer --> n2_analyzer_src_language_config n7_s_analyzer_src_file_analyzer --> n6_packages_analyzer_src_parser n4__analyzer_src_file_discovery --> n2_analyzer_src_language_config

Dependencies

17 of 63 declared dependencies are a major version behind. Resolved 61 of 63 against the registry.

Package	Declared	Latest	Behind
`@types/node`	^22.0.0	26.2.0	4 major
`uuid`	^11.0.0	14.0.1	3 major
`typescript`	^5.7.0	7.0.2	2 major
`@vitejs/plugin-react`	^4.3.0	6.0.5	2 major
`vite`	^6.0.0	8.2.1	2 major
`@ai-sdk/anthropic`	^3.0.58	4.0.39	1 major
`@ai-sdk/openai`	^3.0.41	4.0.42	1 major
`ai`	^6.0.116	7.0.66	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low2

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

pnpm/action-setup@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Replace the wildcard CORS origin with an explicit allow listhigh

apps/server/src/index.ts

cors()

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/test.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

6 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium2 occurrences

assets/demo.gif

2 blobs over 5MB: demo.gif 15.2MB, demo.mp4 7.2MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/publish.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/publish.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.