Fondamenta ArchCode

Zero-dependency codebase intelligence for AI agents and humans.

Static analysis → structured Markdown → readable by any LLM. No graph database, no MCP server, no cloud service. Just .md files committed to your repo.

Why?

Every AI coding tool (Claude Code, Cursor, Copilot) needs to understand your codebase. Current solutions require running servers or databases. Fondamenta ArchCode generates structured Markdown files that any LLM can read natively — no special tools needed.

npx fondamenta-archcode analyze

That's it. Your .planning/ directory now contains a complete architectural analysis.

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

Each file is:

• Human-readable — open in any editor, review in any PR
• AI-readable — any LLM understands Markdown natively
• Grep-friendly — find anything with standard tools
• Git-friendly — meaningful diffs when your code changes

Quick Start

# Analyze current project
npx fondamenta-archcode analyze

# Analyze specific directory
npx fondamenta-archcode analyze ./my-project

# Custom output directory
npx fondamenta-archcode analyze --output .docs

# Initialize config file
npx fondamenta-archcode init

Sample Output

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`
- **i18n:** `dashboard`

api-routes-atomic.md

### `/api/courses`

- **File:** `app/api/courses/route.ts`
- **Methods:** `GET`, `POST`
- **Auth:** auth()
- **Models:** `course`, `enrollment`
- **Side Effects:** DB: findMany, DB: create

schema-crossref-atomic.md

### `User`

| Field | Type | Constraints |
| --- | --- | --- |
| `id` | `String` | primary key, @default(cuid()) |
| `email` | `String` | unique |
| `name` | `String` | optional |
| `courses` | `Course` | array |

**Relations:**
- `courses` → `Course` (one-to-many)
- `flashcards` → `Flashcard` (one-to-many)

Configuration

Create fondamenta.config.ts (or run npx fondamenta-archcode init):

import { defineConfig } from 'fondamenta';

export default defineConfig({
  output: '.planning',
  framework: 'auto',         // 'nextjs-app' | 'nextjs-pages' | 'nuxt' | 'sveltekit' | 'remix'
  language: 'en',
  generators: {
    pages: true,
    components: true,
    apiRoutes: true,
    lib: true,
    schemaXref: true,
    componentGraph: true,
    dependencyMap: true,
  },
  exclude: ['**/node_modules/**', '**/*.test.*'],
  schema: {
    provider: 'auto',        // 'prisma' | 'drizzle' | 'none'
  },
});

Frameworks Supported

Framework	Status
Next.js App Router	Supported
Next.js Pages Router	Supported (basic)
Nuxt 3	Planned
SvelteKit	Planned
Remix	Planned

How it works

1. Discovers files using fast-glob (respects .gitignore)
2. Parses TypeScript/TSX using the TypeScript Compiler API (not regex)
3. Builds an in-memory graph of imports, exports, components, hooks
4. Classifies each file: page, component, API route, lib, hook
5. Analyzes Prisma schema for models, fields, and relations
6. Generates structured Markdown with consistent formatting

Zero runtime dependencies after analysis — output is plain Markdown.

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)
Incremental	Yes (watch + diff)	Re-index	No

Commands

Command	Description
fondamenta analyze [path]	Full codebase analysis → Markdown files
fondamenta analyze --incremental	Only analyze git-changed files
fondamenta analyze --no-preserve-manual	Skip manual section preservation
fondamenta agents [path]	Run code health agents on the project graph
fondamenta agents --json	Output findings as JSON (for CI/tools)
fondamenta diff [path]	Show changes since last analysis
fondamenta watch [path]	Watch mode — regenerate on file changes
fondamenta ai-context [path]	Generate AI context files
fondamenta init	Create configuration file

fondamenta agents

Run 8 code health agents (3 free, 5 PRO) that analyze your project graph and produce actionable findings.

fondamenta agents              # All available agents
fondamenta agents --free       # Free agents only
fondamenta agents --agent dead-code  # Single agent
fondamenta agents --ci         # Exit code 1 if errors found
fondamenta agents --report     # Generate AGENTS-REPORT.md
fondamenta agents --list       # List all agents with tier

Free agents:

Agent	What it checks
dead-code	Orphan components, unused exports, unreferenced lib files
circular-deps	Circular import chains (DFS cycle detection)
architecture-guard	Oversized files, god components, unprotected mutation routes

PRO agents (license required):

Agent	What it checks
security-scanner	Auth gaps, env var leaks, insecure patterns
schema-drift	Code↔schema model mismatches
performance-sentinel	Heavy pages, unnecessary client components, API waterfalls
convention-enforcer	Naming, barrel exports, auth pattern consistency
impact-analyzer	Fan-in/out hotspots, hub components, bridge files

fondamenta diff

fondamenta diff                # Show what changed
fondamenta diff --ci           # Exit code 1 if outdated (for CI)

fondamenta watch

fondamenta watch               # Watch and regenerate on changes
fondamenta watch --debounce 1000  # Custom debounce (ms)

fondamenta ai-context

fondamenta ai-context --claude    # Generate/update CLAUDE.md
fondamenta ai-context --cursor    # Generate .cursorrules
fondamenta ai-context --copilot   # Generate .github/copilot-instructions.md
fondamenta ai-context --all       # All of the above

Manual Sections

Fondamenta preserves human-written content across regenerations. Add manual sections using markers:

<!-- MANUAL-START:my-notes -->
Your custom notes here — they survive `fondamenta analyze`
<!-- MANUAL-END:my-notes -->

Or use the split-point pattern — everything after ## Manual Notes is preserved:

## /dashboard
(auto-generated content above)

## Manual Notes
Your custom architecture notes here — preserved across regeneration.

Disable with --no-preserve-manual.

Incremental Mode

Only regenerate documentation for files changed since last commit:

fondamenta analyze --incremental

Uses git diff to detect changed .ts/.tsx/.vue files and skips unchanged files. Combined with writeIfChanged (always active), only files with actual content changes are written to disk — zero noise in git diffs.

Automation

Cron (recommended for servers)

# Regenerate every 6 hours
30 */6 * * * cd /path/to/project && fondamenta analyze > /dev/null 2>&1

Git pre-commit hook

# .git/hooks/pre-commit
fondamenta analyze
git add .planning/

GitHub Action

- name: Update architecture docs
  run: npx fondamenta-archcode analyze
- name: Commit changes
  run: |
    git add .planning/
    git diff --staged --quiet || git commit -m "docs: update fondamenta analysis"

Roadmap

• CLI analyze command
• Next.js App Router support
• Prisma schema analysis
• 7 atomic generators + dependency map
• fondamenta watch (incremental rebuild)
• fondamenta diff (show changes since last analysis)
• AI context generation (.cursorrules, CLAUDE.md, copilot instructions)
• Code health agents (8 agents: dead code, circular deps, security, performance, etc.)
• Open Core licensing (3 free + 5 PRO)
• Manual sections preservation (marker-based + split-point)
• Incremental mode (--incremental via git diff)
• writeIfChanged (zero-noise git diffs)
• Test suite (120+ tests, CI with GitHub Actions)
• GitHub Action (marketplace)
• Multi-framework support (Nuxt, SvelteKit, Remix)
• Ed25519 license validation (upgrade from HMAC)

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT