Turn the page into an architecture

How do I turn a sketch into a software architecture?

Translate each symbol on the page into a part of the system.

• Boxes become services. Each box in the architecture row is a service with one job. If a box does two jobs, split it.
• Cylinders become data stores. Name what lives in each one and what writes to it.
• The star becomes a pipeline. Wherever the AI sits, it becomes a retrieval step, a draft, a reviewer and a confidence gate. Not a single call that returns an answer.
• The hand becomes an approval. A real step in the system that nobody, including the AI, can skip.

Write it down as a short list or a simple diagram. Then give it to Claude and ask it to check, not to design: "Here is the architecture I decided. What's missing, what breaks first, and what would you remove?"

You decide. Claude checks.

What is a confidence gate in an AI app?

A confidence gate is the step that decides what happens to an AI output before anyone sees it. The shape is the same every time:

retrieval → draft → reviewer → confidence gate → send · flag · ask a human

The reviewer checks the draft against the evidence it was built from. The gate scores the result. High confidence goes out. Medium is flagged for a person to check. Low goes to a named human. The filled example in the free build-brief template uses 0.8 and 0.5 as the cut-offs. Set yours with the people who own the outcome.

Where should a human approve what the AI does?

Grade each task with one question: what happens if this is wrong? If a mistake costs a minute, the step can run on its own. If a mistake is a bad draft someone would catch, a person edits before it goes out. If a mistake costs money or reputation, the AI prepares and a human decides.

Anything that leaves the building, like an email, a payment or a client-facing answer, passes the gate.

Which questions find the gaps in an architecture?

Ask what happens at scale, and what happens when something is down. "What happens at ten times the users?" and "What happens the day the model is unavailable?" turn a diagram that works on a whiteboard into one that survives a busy day. Ask them about each service, not the system as a whole.

What are the common mistakes?

• Asking the AI to design it. You decide, Claude checks. Don't let AI make the decisions you haven't made.
• One big AI call. A single prompt that retrieves, reasons and answers can't be checked. Split it so each part has an output your code can verify.
• No reviewer step. If nothing checks the draft against the evidence, the system is guessing in a confident voice.
• A hand that can be skipped. An approval with a bypass for urgent cases is not an approval.
• More boxes than the page. The architecture should be no bigger than the honest page from step 2.

Which templates help with this step?

The architecture row of The page is where this starts. Autonomy levels grades each task, which tells you where the hand goes. If the AI answers from documents, RAG that doesn't guess gives six checks for the retrieval part: a source of truth, evidence, a score, a refusal path, real data and a reviewer.

What did the architecture look like in the real JobFuture build?

The system map was a browser, Next.js, FastAPI, MongoDB Atlas, a worker and the Claude API. Then the AI context architecture: six model calls, what goes into each one, what comes back, and the checks our code runs on every output.

the system map

Then the question that found three real gaps: what happens at 1,000 users? First, the worker handled one job at a time. Second, fifty people entering the same job title would trigger fifty identical web searches. Third, rate limits and spend.

Each gap became a decision: an asynchronous worker, one research per role, rate limits and a spend cap. Every model call ran in the worker, with a schema our code checked. Watch episode 2.