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.
The Solution: Structured Markdown
Fondamenta ArchCode runs static analysis on your codebase and generates structured Markdown files. That's it.
npx fondamenta-archcode analyze
No database. No server. No runtime dependencies. Just .md files that any LLM can read natively.
What It Generates
.planning/
├── DEPENDENCY-MAP.md # Architecture overview, impact areas
└── 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.
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
The TypeScript Compiler API is key here — it gives us a real AST, not fragile regex patterns. We can detect server vs client components, extract hooks, find API calls, and trace the full dependency tree.
Real-World Results
Tested on a 1000+ file Next.js project:
| Metric | Count |
|---|---|
| Pages analyzed | 116 |
| Components mapped | 487 |
| API routes documented | 291 |
| DB models cross-referenced | 109 |
| Total time | < 3 seconds |
Beyond analyze: Full Workflow
# Detect what changed since last analysis
fondamenta diff
fondamenta diff --ci # Exit code 1 if outdated (for CI pipelines)
# Watch mode — regenerate on file changes
fondamenta watch
# Generate AI context files
fondamenta ai-context --claude # CLAUDE.md
fondamenta ai-context --cursor # .cursorrules
fondamenta ai-context --copilot # copilot-instructions.md
fondamenta ai-context --all # All of the above
vs Alternatives
| Fondamenta ArchCode | GitNexus | Repomix | |
|---|---|---|---|
| Output | Structured .md files | Graph DB (KuzuDB) | Single concatenated file |
| 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 |
| 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
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)