The Live Project Overview

TLDR

ARCHITECTURE.md captures intent — the design you agreed at planning time. The overview/ folder captures reality — what entities, routes, and automations actually exist in the codebase right now.

It's a generated, committed set of focused markdown files (stack.md, entities.md, routes.md, automations.md, plus dated decision stubs). One Node script keeps it current. AI reads only the file relevant to the current task instead of a monolithic doc that wastes tokens. PRs surface drift the moment it appears. A non-technical operator can open entities.md and understand the system in 60 seconds.

Build it Sprint 1, like the control panel. Cost to regenerate: ~$0.00 — it's a local script, no AI involved.

---

Why Generated, Why a Folder

Hand-maintained docs drift. You add a column to a table, refactor a route, wire a new webhook — and ARCHITECTURE.md quietly slips out of sync. Three sprints later, half of it is wrong, and AI sessions confidently make decisions from stale information. This isn't a documentation discipline problem. It's a structural one: anything maintained by hand will rot the moment a deadline pressure hits.

Two failed alternatives prove the point. Mermaid diagrams look beautiful in the readme but freeze the moment they're committed; nobody updates them. A single fat OVERVIEW.md stays current for a sprint or two, then becomes a 2,000-line wall of text that AI reads in full on every task — token-expensive and harder to navigate than the codebase itself.

The two principles that fix this:

1. Generate from source-of-truth. Read package.json for the stack. Read domain.config.js for entities. Scan src/routes/ for routes. The codebase is the truth; the docs reflect it. If the script and the code disagree, the script wins.
2. Split into focused files. AI reads only the file relevant to the current task. Adding a route? routes.md. Adding a column? entities.md. Doing neither? Just README.md — one page.

The result is the documentation equivalent of the control panel: runtime visibility into the system, but for AI sessions instead of humans clicking around. It extends, rather than replaces, the Documentation Architecture pattern — ARCHITECTURE.md still owns intent and design rationale.

---

The Folder Layout

overview/                     ← generated, committed
├── README.md                 ← 1-page index: what the app is + recent decisions
├── stack.md                  ← from package.json + deployment.json
├── entities.md               ← from domain.config.js / DB introspection
├── routes.md                 ← from src/routes/ scan + JSDoc descriptions
├── automations.md            ← from flow-registry.js
├── decisions/                ← dated ADR stubs, AI appends one per non-obvious call
│   ├── 2026-04-12-svelte-flow-for-flows.md
│   └── 2026-04-18-cache-headers-default.md
└── DRIFT.md                  ← only generated when generator detects mismatch with ARCHITECTURE.md

README.md — the only file AI reads on every task. One page, ~500 tokens. What the app is, quick stats (entity count, route count, automation count), the last three decisions, and a pointer to each sibling file. Small enough that "always read it" is cheap.

stack.md — frameworks, services, hosting. Generated from package.json (with versions) and deployment.json (services and URLs). AI reads it when adding dependencies, debugging version-specific issues, or deploying.

entities.md — every data entity with an English description, key fields, relationships. Generated from domain.config.js (your declared source of truth) with optional cross-validation against the live database schema. AI reads it when adding fields, designing queries, or wiring forms.

routes.md — every URL the app exposes, with a one-line description per route taken from a leading JSDoc on the route file. Generated by scanning src/routes/ for +page.svelte, +page.server.ts, and +server.ts files. AI reads it when adding pages or APIs.

automations.md — every backend automation (webhook, cron, pipeline) with trigger and steps. Generated from flow-registry.js (the same convention the control panel uses). AI reads it when wiring or modifying flows.

decisions/ — dated ADR stubs, three to five lines each: what changed, why, what alternatives were considered. AI appends one whenever it makes a non-obvious call.

DRIFT.md — only present when the generator detects that the live codebase contradicts something in ARCHITECTURE.md. Its existence is the signal: stop and reconcile before further work.

---

The Generator

A single Node script: pnpm generate:overview. It reads:

• package.json → stack frameworks and versions
• deployment.json → services and hosting (the same file the control panel uses)
• domain.config.js → entities with descriptions and relationships
• src/routes/ → route files plus their leading JSDoc
• src/lib/config/flow-registry.js (if present) → automations
• Optionally introspects the live database schema to cross-check domain.config.js

It outputs the markdown files above. Re-run on demand or — better — as the last step of every task before commit.

A 30-line sketch of what the generator does for entities.md:

// scripts/generate-overview.js (excerpt)
import fs from 'node:fs';
import domain from '../domain.config.js';

const lines = [
  '# Entities',
  '',
  '> Generated from `domain.config.js`. Edit there, regenerate here.',
  '',
  '## Summary',
  '',
  '| Entity | What it is | Key fields | Related to |',
  '|---|---|---|---|',
];

for (const e of domain.entities) {
  const fieldNames = e.fields.slice(0, 3).map(f => f.name).join(', ');
  const related = (e.relationships ?? []).join('; ') || '—';
  lines.push(`| ${e.name} | ${e.description} | ${fieldNames} | ${related} |`);
}

fs.mkdirSync('overview', { recursive: true });
fs.writeFileSync('overview/entities.md', lines.join('\n') + '\n');
console.log(`✓ entities.md (${domain.entities.length} entities)`);

That's the whole pattern: read declarative truth, format as a table with an English-description column, write the file. Each output file is a 30-50 line transformation. No fancy libraries, no template engine, no AI calls. The whole script is usually under 200 lines for a typical project.

---

The Conventions That Make It Work

The generator only works if a few small habits stay in place. Encode them as iron-clad rules.

File / Convention	Purpose	AI Rule
domain.config.js	Entity definitions with English descriptions	Update when adding/changing entities
Route JSDoc	One-line description per +page.server.ts and +server.ts	Add before any new route
overview/decisions/	Dated ADR stubs (3-5 lines each)	Append when making any non-obvious call
pnpm generate:overview	Regenerate the folder	Run as last step of every task before commit
overview/DRIFT.md	Generator-flagged mismatch with ARCHITECTURE.md	If present, READ IT before doing anything else

The five rules to drop into .clinerules and CLAUDE.md:

• Read overview/README.md at the start of every task. It's small, ~1 page, your map of current state.
• Read additional overview/*.md files only when the task touches them. Be selective — adding a route reads routes.md, adding an entity reads entities.md. Do not read all of them.
• Update domain.config.js whenever entities change. Adding a field, a relationship, a new entity — change it there, not just in code.
• Add a JSDoc one-line description to every new route file. The generator reads these to build routes.md.
• Append a decision stub to overview/decisions/ whenever you make a non-obvious call. Format: YYYY-MM-DD-short-slug.md, three lines: what changed, why, alternatives considered.
• Run pnpm generate:overview as the last step before committing. Commit the regenerated folder. PR diffs surface drift.

The exact wording of these rules ships in the project templates.

---

When to Build It

Sprint 1 default for any project with a backend or any non-trivial data model. The empty templates and the generator script ship with project scaffolding — same posture as the control panel and the cache-header rules.

The first sprint wires up whatever the project actually has — usually entities and routes. Automations and decisions populate naturally as those things appear. There's no upfront cost: an empty automations.md is fine, the generator skips sections it has no source data for.

What you spend on this:

• Building the generator: one task, usually 60-90 minutes of Cline time
• Regenerating: ~$0.00. It's a local Node script, no AI involved.
• AI reading overview/README.md at task start: maybe 500 tokens — cents per task at most.

What it saves:

• Re-explaining the system to AI at the start of every task (easily several thousand tokens otherwise)
• Drift bugs where AI confidently writes code against ARCHITECTURE.md's outdated description of an entity
• The slow rot of ARCHITECTURE.md itself — generated overview makes drift visible, which makes it easy to fix

By the time you've avoided two drift-induced bugs, the generator has paid for itself permanently.

---

What Non-Tech People See

Open overview/entities.md and you get something like this:

# Entities

## Summary

| Entity | What it is | Key fields | Related to |
|---|---|---|---|
| Member | A person who has signed up. Members register for events, complete courses, receive newsletters. | id, email, name | Registrations; Enrolments |
| Event | A workshop or talk a member can register for. Has a date, location, and capacity. | id, title, starts_at | Registrations; Speakers |
| Course | A multi-week programme a member can enrol in. Tracks progress per module. | id, title, modules | Enrolments |

A consultant brought in for a week, a future you returning to the codebase after three months, a client asking what the system actually does — they all open this one file and understand the shape of the app in under a minute. No code reading, no schema diagrams, no internal jargon. Just the entities in the language the business uses.

This is the closest the methodology gets to giving non-technical operators what Bubble or Pocketbase gave them visually: a single page that answers "what is this system?" in plain English. The control panel does the same for runtime; the overview folder does it for structure.

---

Drift surfaces in PR diffs

Because overview/ is committed, every change to entities, routes, or automations shows up as a diff alongside the code change. You see the structural intent in the same review as the implementation. If a PR's code change isn't reflected in the regenerated overview, that's a flag — either the generator wasn't re-run, or something subtler is wrong.

---

Next: The Execution Workflow — How to actually run AI-assisted tasks.