Code Architecture Review
Pressure-test a system design before you commit to it.
A verdict on the design with the riskiest decisions and concrete alternatives.
Architecture reviews go soft when everyone shares the designer’s assumptions, so the seats are chosen to collide: the Software Architect judges boundaries and coupling, the Reliability Engineer asks what breaks at 3 a.m., the Security Engineer walks the trust boundaries, and the Performance Engineer finds the wall the design hits at ten times the load. The CTO weighs build cost against the team that must maintain it, and the Pragmatist defends the simplest design that meets the real requirement — usually against everyone else.
Review this architecture / system design and argue the trade-offs out. THE DESIGN: [describe or paste the architecture — components, data flow, key choices, tech stack] CONSTRAINTS: [scale, team, latency/throughput needs, deadlines] WHAT WORRIES YOU: [your own doubts, if any] Debate: 1. Boundaries and coupling — are the seams in the right places; what is hard to change later. 2. Accidental complexity and premature abstraction versus genuinely needed flexibility. 3. The data model and ownership — single source of truth, consistency, migrations. 4. Failure modes — what breaks, the blast radius, recovery and observability. 5. Scale — where this design hits a wall and what it costs to fix then. 6. Security and trust boundaries. 7. The simplest design that would still meet the real requirements. FINAL SYNTHESIS: - A verdict: sound / sound-with-changes / rethink. - The one or two decisions that are hardest to reverse, and the recommendation on each. - A concrete list of changes, severity-ranked, with the reasoning.
An illustrative excerpt for a hypothetical brief of this type: A four-engineer team is proposing to split their monolithic booking platform into nine microservices with an event bus before onboarding their biggest customer yet. Every real run is generated fresh from your specifics, debated across rounds, and audited before the verdict.
Nine services for four engineers is more than two services per person — every one adds a deployment, a contract, and a failure mode. The stated goal is isolating the booking engine from reporting load. That is one seam, not eight. Extract the single hot boundary and leave the rest of the monolith alone until a second seam actually hurts.
The event bus is where this design fails operationally: at-least-once delivery means duplicate bookings unless every consumer is idempotent, and the design doc does not mention idempotency once. A monolith’s failure modes are boring and known; distributed failure modes have to be designed, staffed and paged for. Who is on call for nine services?
The numbers do not justify the surgery: current peak is modest, and the big customer multiplies load roughly fourfold. A read replica for reporting queries plus a cache on availability lookups absorbs that with two weeks of work. The proposed architecture solves a scale problem this system does not have yet — and creates a latency problem it does not have either.
Verdict shape: sound-with-changes. One extraction — reporting off the transactional path — plus idempotency keys on booking writes, and the migration stops there. The full decomposition goes in the drawer with the trigger written down: revisit when team size or deploy contention, not ambition, demands it.
Prefer drop-and-go? Use the AI Code & Architecture Review tool — team pre-seated, included with Plus.
What level of detail does the council need — diagrams, code, a doc?
A component list with data flow, the key technology choices, expected scale, and team size — a design doc or an architecture sketch is ideal, but a thorough prose description works. Team size matters as much as the diagram: the same design can be right for forty engineers and wrong for four.
Can it review an existing system rather than a proposed design?
Yes — describe the current architecture and where it hurts (deploy fear, incident frequency, a wall you can see coming). The debate then weighs live constraints, since the cost of change in a running system is a first-class input rather than a footnote.
What does the verdict commit to?
One of sound / sound-with-changes / rethink, plus the one or two decisions that are hardest to reverse and a severity-ranked change list. Reversibility drives the priority: a wrong library choice ages fine, a wrong data-ownership boundary compounds forever.