Architecture

Create or update root ARCHITECTURE.md so a new teammate can understand the system that exists in code today.

The document should reveal the few rules that give the system its shape: where truth lives, which way dependencies point, how important work moves through the system, and which boundaries a change must preserve.

Process

1. Read the request, repository instructions, and any existing ARCHITECTURE.md.
2. Inspect the implementation. Start with manifests, entry points, configuration, schemas, migrations, infrastructure, tests, and the code behind a few critical flows. Follow evidence rather than trying to read every file.
3. Identify the load-bearing facts: the system boundary, trust boundaries, source of truth, main parts, dependency direction, important protocols or data, and the one rule a contributor must not break.
4. Create or update root ARCHITECTURE.md. Preserve useful verified content from an existing document, remove stale claims, and organize the body around the system rather than a generic template.
5. Verify each concrete claim against code, configuration, schemas, infrastructure, or executable tests. Treat existing prose as a claim, not evidence.
6. Run the review pass and stop with the document ready for human review. Do not propose future behavior, write a design, plan work, or change implementation.

Document shape

Start every document with this small common frame: