App Architect

Turn a vague app idea into two files — ARCHITECTURE.md and PLAN.md — then use the plan to drive the build. The value is in forcing three decisions early, in order: what the MVP actually is, what the data looks like, and what stack fits. Everything downstream falls out of those three.

Keep the whole process efficient. The user wants good architecture and working code, not a tutorial. Short answers, concrete artifacts, no lectures.

Choose the entry point

• New project, or a major feature on an existing one → run the full workflow (steps 1–5).
• Narrow architecture question ("should X have a separate backend?", "is this folder layout OK?") → answer it directly in a few sentences using the stack decision rule and references/stack-conventions.md. Then offer the full planning pass; don't force it.
• Refactoring an existing codebase → skip the interview; the code is the interview. See "Refactoring path" below.
• Project already has ARCHITECTURE.md / PLAN.md → read them and update rather than regenerate. Append new milestones; never renumber or rewrite completed ones.

Step 1 — Interview, briefly

One round of questions, 3–5 max, covering: purpose (what problem, for whom), users (one kind or several, roughly how many), and core features (what the user would list). If the request already answers some of this, don't re-ask — fill gaps only.

Then cut the feature list to a true MVP: the smallest version someone could genuinely use. State what was cut and a one-line reason per cut — usually "not needed to validate the core loop" or "can be added later without rearchitecting". Deferring is not deleting: cut features go in a Later list in ARCHITECTURE.md, and the data model may anticipate them where doing so is cheap.

Step 2 — Data first

Before any stack talk, define the data model:

1. Plain language — the main entities and how they relate: "A Course has many Sessions; a Booking links a customer to a Session."
2. TypeScript types — one interface per entity, relations as ids. Only what the MVP needs plus obviously-coming fields.

Data comes first because the model outlives every UI decision: get the entities and relations right and the milestones fall out naturally; get them wrong and it's the most expensive thing in the project to fix.

Step 3 — Stack decision rule

Default: Next.js full-stack — App Router, server actions and/or route handlers, TypeScript, Tailwind, Postgres + Prisma.

Choose a separate Node/Express backend (with a Next.js or React frontend) only when the project needs at least one of:

• background jobs or queues (scheduled work, long-running processing)
• websockets / real-time (live multiplayer, presence, live-updating dashboards)
• an API consumed by multiple clients (web + mobile + third parties)
• heavy non-web server logic (device integrations, protocol servers, big compute)

State the choice and the reason in one short paragraph — in chat and in ARCHITECTURE.md. Don't hedge: apply the rule, pick, say why. If a trigger is speculative ("maybe a mobile app someday"), record it under Key decisions and stay with the default — Next.js route handlers can serve a mobile client later, and extracting a backend is a known refactor, whereas premature separation costs something every day.

Read references/stack-conventions.md before writing ARCHITECTURE.md — it holds the naming rules, folder layouts for both stacks, environment-variable handling, and database conventions the files must follow.

Step 4 — Produce the two files

Create both in the project root.

ARCHITECTURE.md

# <Project> — Architecture

## Stack
<one line per layer: framework, language, styling, database/ORM, auth, deploy target>

## Why this stack
<the one-paragraph outcome of the decision rule>

## Data model
<plain-language entity summary, then the TypeScript interfaces in a ts code block>

## Folder structure
<tree from stack-conventions.md, trimmed to this project's actual needs>

## Key decisions
- **<Decision>** — <choice>. <Reason, one sentence.>

## Later (cut from MVP)
- <feature> — <why cut / when to revisit>

PLAN.md

# <Project> — Build plan

Milestones in build order. Each ends with something you can run and check.
Don't start milestone N+1 until milestone N's "Done when" passes.

## 1. <Milestone name>
- [ ] <step>
- [ ] <step>

**Done when:** <observable check — a command to run, a page to load, a behavior to see>
**Teaches:** <one line — what this milestone establishes>

Default milestone order: scaffold → data model/database → backend logic + API → frontend pages/components → integration → auth (if needed) → polish → deploy.

Milestone rules:

• Each milestone is small and independently testable. If a milestone can't be verified by running something, split or reshape it.
• Auth stays late unless the app is unusable without it — if every row belongs to a user from day one, move auth directly after the data-model milestone.
• Deploy is last, but suggest deploying a skeleton early when the user wants a live URL from the start.

Step 5 — Building milestones

When the build starts (this session or a later one):

1. Before starting any milestone, restate in one sentence what it teaches/establishes.
2. Build only that milestone. Resist pulling work forward from later ones — the plan's value is that each step is verifiable in isolation.
3. Verify the "Done when" condition by actually running it, not by assuming.
4. Tick the checkbox in PLAN.md. If a decision changed mid-build, update ARCHITECTURE.md — a stale architecture doc is worse than none.

Refactoring path

When the trigger is "this codebase is a mess":

1. Read the project first — entry points, routes, where data access lives, what's tangled. If the code isn't available, ask for it before planning anything.
2. Write ARCHITECTURE.md describing the target structure (use the matching layout in references/stack-conventions.md), with the main moves and reasons under Key decisions.
3. Write PLAN.md as incremental milestones that each keep the app working — e.g. extract data access → split routes from business logic → break up god components → add types at the boundaries. Never a big-bang-rewrite milestone.
4. "Done when" for each refactor milestone is: the app still runs and behaves the same, plus the specific move is verifiable.