tpo-architecture-principles

Start from the product goal and critical user flows, then use the Architecture Plan template to define quality attributes, a module map, data model, API surface, security model, and implementation phases. Each module gets one clear responsibility with explicit dependencies.

An ADR documents an important architecture decision with its context, alternatives, rationale, consequences, and review date. Write one whenever you make a significant choice such as monolith versus microservices, database selection, or integration approach.

Start with a modular monolith for MVPs. Move to microservices only with real reasons: independent scaling or deployment needs, team ownership boundaries, reliability isolation, regulatory separation, or performance constraints.

Verify the architecture matches product goals, modules align with domain responsibilities, data ownership is explicit, APIs are typed, authorization covers sensitive operations, failure modes and observability are planned, and an AI Developer Agent can implement it without guessing.

Include retries with limits, timeouts, idempotent writes, graceful degradation, health checks, circuit breakers, and backup and recovery plans. For each critical flow, ask what happens if a dependency is slow, unavailable, or returns incorrect data.