The Problem
Every AI coding tool — Claude Code, Cursor, Copilot — needs to understand your codebase. But they don't. Not really.
They see individual files, but miss the big picture: which components depend on what, how API routes connect to database models, what auth pattern each page uses.
Current solutions like GitNexus solve this with a graph database (KuzuDB) and an MCP server. That's powerful, but it's also heavy: you need to run a server, install dependencies, and it only works with Claude Code.
I wanted something simpler — and I wanted to go further than just mapping code.
The Solution: Structured Markdown + Code Health Agents
Fondamenta ArchCode runs static analysis on your codebase and generates structured Markdown files. But in v0.3.0, it also runs rule-based agents on the project graph to find real issues.
npx fondamenta-archcode analyze # Map everything
npx fondamenta-archcode agents # Find issues
No database. No server. No runtime dependencies. Just .md files and actionable findings.
What It Generates
.planning/
├── DEPENDENCY-MAP.md # Architecture overview, impact areas
├── AGENTS-REPORT.md # Code health findings (with --report)
└── dependencies/
├── pages-atomic.md # Every page: imports, auth, data fetching
├── components-atomic.md # Every component: props, state, hooks, used-by
├── api-routes-atomic.md # Every API route: methods, auth, models
├── lib-atomic.md # Every utility: exports, imports, env vars
├── schema-crossref-atomic.md # DB models, fields, relations, enums
└── component-graph.md # Visual dependency tree
Example: pages-atomic.md
### `/dashboard`
- **File:** `app/(dashboard)/dashboard/page.tsx`
- **Type:** Server Component
- **Auth:** auth()
- **Data Fetching:**
- DB: findMany (courses)
- DB: count (flashcards)
- **Components:** CourseCard, StatsWidget, RecentActivity
Every AI agent understands this format instantly. No special tools needed.
Code Health Agents (NEW in v0.3.0)
This is the real game-changer. After analyze builds the project graph, agents runs rule-based checks on it:
$ fondamenta agents --free
✓ dead-code .............. 3 findings (1 error, 2 warnings)
✓ circular-deps .......... 0 findings
✓ architecture-guard ..... 5 findings (2 warnings, 3 info)
○ security-scanner ....... skipped (PRO)
ERROR [dead-code] Orphan component
│ File: components/legacy/OldWidget.tsx
│ Component `OldWidget` is never imported or rendered
│ → Remove the file or restore the import
8 findings: 1 error, 4 warnings, 3 info | 3 agents ran | 9ms
3 Free Agents
| Agent | What it checks |
|---|---|
dead-code |
Orphan components, unused exports, unreferenced lib files |
circular-deps |
Circular import chains using DFS 3-color cycle detection |
architecture-guard |
Files >500 lines, god components (>15 deps), mutation routes without auth |
5 PRO Agents (license-gated)
| Agent | What it checks |
|---|---|
security-scanner |
Auth gaps + DB access, env vars leaked to client bundles, insecure patterns |
schema-drift |
Models in code but not in schema, schema models never referenced |
performance-sentinel |
Heavy pages (>20 imports), unnecessary client components, API waterfalls |
convention-enforcer |
File naming, barrel exports, inconsistent auth patterns |
impact-analyzer |
Fan-in/fan-out hotspots, hub components, bridge files |
CI Integration
fondamenta agents --ci # Exit code 1 if errors found
fondamenta agents --report # Generate AGENTS-REPORT.md
The business model is Open Core: free agents work for everyone, PRO agents require a license key. No server calls — validation is offline.
How It Works
-
Discovers files using
fast-glob(respects.gitignore) - Parses TypeScript/TSX using the TypeScript Compiler API (not regex!)
- Builds an in-memory graph of imports, exports, components, hooks
- Classifies each file: page, component, API route, lib, hook
- Analyzes Prisma schema for models, fields, and relations
- Generates structured Markdown with consistent formatting
-
Runs agents on the graph — each agent is a pure function:
(graph, config) → findings[]
The TypeScript Compiler API is key — it gives us a real AST. The agents are simple: they iterate over nodes and edges in the graph. No AI, no LLM calls. Pure rule-based analysis that runs in milliseconds.
Real-World Results
Tested on a 1000+ file Next.js project:
| Metric | Value |
|---|---|
| Files analyzed | 1,011 |
| Pages mapped | 116 |
| Components mapped | 487 |
| API routes documented | 291 |
| DB models cross-referenced | 109 |
| Analysis time | 3.4 seconds |
| Agents execution | 9 milliseconds |
| Findings | 601 (40 errors, 550 warnings, 11 info) |
Full Command Set
fondamenta analyze # Full codebase analysis
fondamenta agents # Run code health agents
fondamenta agents --free # Free agents only
fondamenta agents --agent dead-code # Single agent
fondamenta agents --ci # Exit 1 if errors (CI)
fondamenta agents --report # Generate markdown report
fondamenta agents --list # Show all agents
fondamenta diff # Changes since last analysis
fondamenta diff --ci # Exit 1 if outdated
fondamenta watch # Auto-regenerate on changes
fondamenta ai-context --all # CLAUDE.md + .cursorrules + copilot
vs Alternatives
| Fondamenta ArchCode | GitNexus | Repomix | |
|---|---|---|---|
| Output | Structured .md files | Graph DB (KuzuDB) | Single concatenated file |
| Code health agents | 8 agents (free + PRO) | No | No |
| Runtime deps | None | KuzuDB + MCP server | None |
| AI integration | Any tool (reads files) | Claude Code only (MCP) | Any tool |
| Framework-aware | Yes (routes, pages, auth) | AST only | No |
| Schema-aware | Yes (Prisma) | No | No |
| CI-friendly | Yes (exit codes) | No | No |
| Human-readable | Excellent | Requires queries | Poor (wall of text) |
| Git-friendly | Yes (meaningful diffs) | No (binary DB) | Poor (single file) |
Try It
npx fondamenta-archcode analyze
npx fondamenta-archcode agents --free
GitHub: github.com/talionwar/fondamenta-archcode
npm: npmjs.com/package/fondamenta-archcode
Currently supports Next.js App Router + Prisma. Multi-framework support (Nuxt, SvelteKit, Remix) is on the roadmap.
Feedback and contributions welcome!
Top comments (0)