When to use it
When you have an architecture (existing or on the drawing board) and you need a view from above: is it split into the right components, where will it break under load, what are the risks and the tech debt, what should be simplified. Unlike a code review, this looks at the design rather than the lines. The role is a software architect running a review. The output: an assessment by aspect, bottlenecks, risks with severity, and prioritized recommendations.
The prompt (grab it and paste)
You are a software architect running an architecture review. Assess the DESIGN (components and their connections), not individual lines of code. Be specific and honest.
WHAT IS UNDER REVIEW: "<PASTE: architecture description / component diagram / list of services and how they connect / key pieces of code>".
STACK: <languages/frameworks/database/infrastructure>. SCALE AND REQUIREMENTS: <load, SLA, team, what is critical — speed/reliability/cost>. STAGE: <design / MVP / growing / legacy>.
WHAT WORRIES ME: "<if there are specific doubts>".
Go through it aspect by aspect, and for each finding give a severity (critical / important / later) and the reasoning:
1. Decomposition and coupling: are the component boundaries right, is there unnecessary tight coupling, are responsibilities violated, are there dependency cycles.
2. Data: model and storage, consistency, read/write bottlenecks, migrations.
3. Scalability and performance: where it breaks at 10x/100x growth, what becomes the bottleneck, state/cache/queues.
4. Reliability and fault tolerance: single points of failure, what happens when part of the system goes down, retries/idempotency, consistency.
5. Security (at the architecture level): trust boundaries, authentication/authorization between components, storage of secrets and personal data.
6. Operability: observability (logs/metrics/tracing), deployment, rollback, maintenance burden.
7. Technical debt and overengineering: where it is overcomplicated for the current stage and where, conversely, a landmine has been buried.
At the end: 3–5 priority recommendations (what to fix first and why), 1–2 alternative approaches with their trade-offs, and what NOT to touch (if it works, do not break it). If there is too little to go on — say what is missing, do not fantasize about parts you have not seen.
Filled-in example
Under review: "a Node + PostgreSQL monolith, everything synchronous; email sending and PDF generation were added straight into the HTTP request; a single instance". Scale: growing, 50 rps, timeouts have started. Stage: an MVP turning into a product.
Expected AI response: [critical] heavy jobs (email, PDF) inside a synchronous request → timeouts and blocked workers → move them into a queue (BullMQ/Redis) with workers; [critical] a single instance is a single point of failure with no horizontal scaling; [important] no idempotency — retries will send duplicate emails; [important] observability: there is no way to see where the time goes, add metrics/tracing; [later] the monolith is fine for this stage, do not break it into microservices prematurely (overengineering); priorities — queue → stateless instances behind a load balancer → idempotency; alternatives with trade-offs; "do not touch" — the database model itself, it is reasonable. Where there is too little on an unfamiliar module, it asks for details.
Variations
- One aspect in depth. "Focus only on scalability" or "only on fault tolerance" — a detailed pass along one axis.
- ADRs. "Format the recommendations as Architecture Decision Records: context → decision → consequences."
- Two designs. "Compare the current architecture with the proposed alternative — a pros/cons table and when each is better."
Pro tips
- Stage and requirements decide everything: "good enough" for an MVP and for a high-load product are different answers. Without scale, SLA and team size the AI will either overcomplicate things or miss a risk. Always give it the requirements and the stage.
- The most valuable parts are the priorities and the "what NOT to touch": the AI loves to suggest "rewrite it as microservices" where that is overengineering. Insist on severity levels and on a guard against premature complexity.
- This is deep architectural judgement — use the strongest model (Opus/GPT-4 class) with a large context; for high stakes run TWO independent reviews and compare. An AI review complements a live architect and load testing, it does not replace them.