Most architecture documents are organized by system layer. There is another useful axis: time. Put decisions together according to how often you expect them to change.
This turns the document from a snapshot into a maintenance plan. It also tells a future reader whether a value is a foundational constraint or merely what happened to fit in the instance last Tuesday.
A time-shaped outline #
1. Overview #
Describe the system’s purpose, background, and overall shape. This is the map legend; keep it short enough that people still read the map.
2. System core: long-term stability #
Expected cadence: three years or longer, with rare changes.
These choices are expensive to replace and define the system’s foundations:
- primary languages, frameworks, and databases;
- monolith, microservice, or layered architecture patterns;
- authentication and authorization foundations;
- system-wide encryption and access-control policies.
Record the important decisions as ADRs. The architecture document says what the current core is; an ADR preserves why the team chose it.
3. Service platform: medium-term evolution #
Expected cadence: one to three years.
These capabilities should evolve deliberately with the business and technology:
- CI/CD strategy;
- monitoring, logging, and analysis platforms;
- test strategy and coverage expectations;
- ETL pipelines, queues, and other integration infrastructure.
4. Operations and improvement: short-term change #
Expected cadence: weeks to months, including continuous tuning.
Put operational values here:
- instance sizes and CPU or memory allocations;
- alert thresholds and destinations;
- cost optimizations and reservations;
- rollout percentages and deployment parameters.
Why this works #
Ownership becomes clearer because every section implies an update rhythm. Stable decisions stop receiving pointless drive-by edits, while volatile values are easy to find and review. The time horizon also preserves intent: a reader can see why one decision was treated as foundational and another as adjustable.
The ordering tends to mirror dependency direction. Short-term operational settings depend on medium-term platform choices, which depend on the long-term core. The core should not depend on next month’s instance size. If it does, congratulations: the document found an architectural smell before production did.
Do not turn estimates into commandments #
The categories are deliberately subjective. Say so in the document. Do not spend a week debating whether a decision belongs in the 35-month bucket or the 37-month bucket.
“Long-term” means the team expected a choice to remain stable when it was made. It does not mean future engineers are forbidden to change it. Architecture is a record of reasoning, not a curse tablet.