An architecture blueprint assistant
Lesson 11 of 12
11An architecture blueprint assistant
The big pictureArchitecture is decisions that are hard to change later: where data lives, how the parts talk, what happens on failure. The assistant speeds up exploring options, but the decision rests on your numbers.
What the picture shows: From requirements to a written decision. Questions before design save most mistakes.
Map of this part
The concepts in order, click any one to jump to it:
Two ways into the same idea
Before building a house the engineer asks: how many people will live there? Will you add a floor later? What is the budget? Building without asking might give you a palace when you need a flat. The assistant is the same: make it ask you first.
Start with non-functional requirements in numbers: concurrent users, requests per second, data size and growth, acceptable latency (p95), required availability, budget and team. Ask the model for clarifying questions first, then at least two options (say a modular monolith versus services) with explicit trade-offs, then a C4 container-level diagram in Mermaid, then an ADR in the form: context, decision, alternatives, consequences. Beware "over-sizing": models tend to suggest Kafka and Kubernetes for a project a single server and database would serve.
Before You Start
🗄️Databases and APIs
You know SQL and REST.
📐API Prototyper
Lesson 8 of this track: design before code.
The Core Idea
1Make it ask first
The first request asks not for a design but for questions:
I am designing the backend for a café ordering app. Before proposing anything, ask me up to 8 questions about load, data, latency, availability, budget and team that would change the design. Do not propose an architecture yet.
2Two options and trade-offs
Ask for at least two options in a table: complexity, cost, ease of deployment, point of failure, and when each option becomes wrong. One option means you never saw the alternatives.
3The diagram and the decision record
Ask for the diagram as text (Mermaid) so it lives in the repository and is reviewed like code, then a short ADR:
flowchart LR app[Mobile app] --> api[API server] api --> db[(PostgreSQL)] api --> cache[(Redis)] api --> pay[Payment provider] # ADR 001: one API server with PostgreSQL Context: 300 orders at peak, 2 developers, budget for one small server. Decision: a modular monolith on one server, PostgreSQL, Redis for the menu cache. Alternatives: services + queue (rejected: operational cost for a team of two). Consequences: simple to deploy; revisit if peak passes 50 orders/second.
Worked example
Problem: the assistant proposed five microservices and Kafka for a clinic booking app. Questions: how many bookings a day? 200. How many developers? One. Re-ask: "what is the simplest architecture for these numbers?". Result: one server, PostgreSQL and a scheduled job for reminders, with an ADR saying when to revisit (10× the bookings).
Myth vs Reality
| Myth | Reality |
|---|---|
| The best architecture is the newest. | The best is the simplest one that meets your numbers and your team can run. |
| The assistant knows your project's size. | It knows only what you tell it, so it assumes the general case. |
Test your understanding
What do you ask the assistant for first when designing an architecture?
Questions reveal the numbers and constraints that change the design.
What does an ADR contain?
It keeps why the decision was made, not only what.
Why ask for the diagram in Mermaid?
A text diagram changes with the code in the same pull request.
Quick review cards
Check Your Understanding
What is the sign the assistant over-sized the solution?
Operational parts (a broker, a container orchestrator) the load or team numbers do not justify.
When do you revisit the decision?
At the threshold written in the ADR's consequences, like a tenfold load increase.
Why at least two options?
To see the trade-offs; a single option hides what you give up.