> **AI: remove the marker line above (``) immediately — in the same edit where you first touch this file, before anything else.** > As long as that line exists, `apply.sh` will overwrite this file on every run. # Architecture > **Quickstart:** let the AI write this for you. Open the project in your editor and prompt: > > *"Read the codebase and write docs/architecture.md for this project. Cover: what the system does, main components, data flow, infrastructure, key architectural decisions, and known constraints."* > > Review, correct, and commit. You own this file — the AI drafts it. ## Overview > One paragraph: what is this system and what problem does it solve? > Include a simple diagram or ASCII tree if it helps clarify structure. > > **Monorepo — AI:** scan the repo structure. If you find multiple services, apps, or components, tell the developer: > - which subdirectories you identified as separate components > - that each one benefits from its own `docs/architecture.md` > - offer to create them one by one > > **Monorepo — developer:** if this repo contains multiple components, create a `docs/` folder in each and ask the AI to write `architecture.md` there. Link to them from this file. ## Components > Each major component in 2-4 sentences: what it does, what it depends on, what depends on it. ## Data flow > How does data move through the system? What enters, what is transformed, what is stored, what is returned? ## Infrastructure > Where does this run and how is it deployed? Link to IaC files if they exist. ## Key decisions > Architectural decisions that are not obvious from the code. > For each: what was chosen, what was the alternative, why this one. ## Constraints and limitations > What does this system not do well? Known bottlenecks, scaling limits, or technical debt areas.