Architecture documentation should answer practical questions: what is this system, who uses it, what does it depend on, and how does a critical request move through it?
Start with system context
Identify users, external systems, trust boundaries, and the responsibilities the application owns. A context diagram should show meaningful relationships rather than every internal class.
Describe containers and modules
Show deployable units, data stores, queues, and important internal modules. Explain ownership and the direction of dependencies. Keep names aligned with the repository so readers can find the corresponding implementation.
Document runtime flows
Choose a few critical scenarios such as login, checkout, content publication, or background processing. Show the sequence of components, important decisions, failure paths, and data changes.
Keep documentation close to reality
Store diagrams and decision records with the code when possible. Assign an owner and update documentation when a meaningful boundary or runtime flow changes.
Checklist
- Explain system purpose and external actors.
- Show deployable components and data stores.
- Document critical success and failure flows.
- Link diagrams to code and ownership.
- Update documentation as part of architectural changes.