📐 Solution Design

A blueprint is the technical specification for the automation — a document that describes each component, the data going in and out, and how the pieces connect, before you touch any tools.

Building without a blueprint means improvising in the editor: you get lost, rework things, and discover failures late. The blueprint makes the problem visible and inexpensive to fix on paper.

Specification ≠ implementation · think before you build · a blueprint that’s easy to read for someone who won’t be building it.

Take each box in the to-be diagram and classify it as a component type: what triggers (trigger), what moves/transforms data (steps), what reasons (AI), and what produces an effect in the world (actions).

Without this translation, the diagram is just a pretty picture. Classifying it into components reveals exactly how many integrations, prompts, and nodes you’ll need.

1 box = 1 or more components · separate deterministic logic from AI · name each component.

The backbone of almost every AI automation follows six stages: something triggers it, data is collected, AI interprets it, a decision is made, an action is executed, and everything is logged.

Knowing the standard anatomy gives you a reusable template: fit any new case into these six stages instead of inventing the structure from scratch.

6 canonical stages · the log is never optional · decision is separate from action.

For each component, explicitly define what goes in and what comes out, and in what format (text, JSON, file, number). This is the contract that connects one piece to the next.

Most workflow failures happen at the handoff: one component delivers a format the next one can’t understand. Defining formats in the blueprint prevents this before it happens.

Data contract · JSON as a lingua franca · required vs. optional fields.

For each component, map what could go wrong (API outage, missing data, uncertain AI output) and define the fallback behavior: retry, skip, alert a human, or stop.

Automation without a plan B is fragile: the first exception brings everything down. Anticipating failures in the blueprint is what turns a prototype into something truly reliable.

Retry vs. fallback · human-in-the-loop · fail loudly, never silently.

Define, before building, what counts as success: time saved, accuracy rate, % of cases that require human intervention, cost per run.

Without a success metric defined up front, you never know whether the automation is good enough to deliver—or whether it’s actually creating more work.

Metric before building · manual baseline · cost per run matters.

Three ways to orchestrate automation: n8n (low-code, self-hosted, flexible), Make (visual, SaaS, quick to get started), and pure code (maximum control, maximum maintenance).

Choosing the wrong foundation costs you later: you run into licensing limits, a missing connector, or complexity that low-code can't support. Choosing carefully avoids a future migration.

Low-code vs. code · self-hosted vs. SaaS · maintenance cost is part of the cost.

Decide whether the task really needs an LLM (vs. a rule/regex) and, if so, which model: a small, inexpensive one for classification, or a large, expensive one for complex reasoning.

Using the most expensive model for everything burns through your budget; using the cheapest for a difficult task undermines reliability. Matching the task to the model keeps cost and quality under control.

An LLM isn't the answer to everything · use a small model for a simple task · cost per token × volume.

RAG (Retrieval-Augmented Generation) searches for relevant passages in your own knowledge base and injects them into the prompt, making AI respond based on your documents, not just its training.

When automation depends on information that only exists at your company (policies, catalog, history), RAG is what keeps AI from making things up and grounds it in the truth.

Retrieve before generating · embeddings and semantic search · RAG only when you have proprietary knowledge.

MCP (Model Context Protocol) is a standard for connecting AI to external tools—reading files, querying databases, calling APIs—in a consistent way, without glue code for each integration.

When automation requires AI to take action (not just respond), MCP standardizes that access. Understanding when to use it helps you avoid reinventing connectors and keeps your stack scalable.

Standardized protocol · AI that uses tools · connector reuse.

The plumbing of automation: APIs (you request data), webhooks (the system notifies you), and databases (you store and query state), with Supabase as an example of a database + API + auth in one package.

Almost every useful automation needs to fetch, receive, or persist data. Knowing the difference between an API and a webhook, and when you need a database, is what connects the workflow to the real world.

Pull (API) vs. push (webhook) · state needs a database · Supabase as a shortcut.

A set of criteria for comparing options: cost, delivery speed, maintenance, control, scaling limits, and vendor dependency — and the recognition that every choice involves trade-offs.

Stack decisions made out of trend or habit are costly. An explicit trade-off chart forces you to justify each choice and defend it to the client.

There’s no free choice · explicit criteria · when options are tied, simple wins.

Treat the prompt not as a conversation, but as a piece of a specification: precise, unambiguous instructions that define exactly how the AI is expected to behave within the workflow.

In automation, there’s no human to correct the AI in real time. The prompt needs to be right from the start — it’s code that runs on its own a thousand times.

Prompt = code in natural language · zero ambiguity · write for the machine, not for conversation.

A reusable skeleton: define the AI’s role, provide the necessary context, specify the task, set the output format, and list the rules and constraints.

Ad hoc prompts produce inconsistent results. A fixed structure makes behavior predictable and the prompt easy to review and maintain.

Role + context + task + format + rules · named sections · reusable template.

Ask the AI to respond in JSON with fixed fields, then validate that response before using it—so the next step in the flow always receives the same structure.

Free-form text breaks automation: the next step doesn't know where each piece of information is. Validated JSON is what makes the AI output reliable enough to feed an automated action.

JSON with a schema · validate before use · reject and retry if invalid.

Guardrails are limits in the prompt and validation (what the AI can't do, what to reject); fallback is what happens when the AI isn't sure or breaks the rules: ask for confirmation, escalate, or use a default value.

AI makes mistakes and hallucinates. Guardrails and fallbacks are what keep a mistake from turning into an automatically executed irreversible action.

Limit what AI can do · confidence field · safe path when uncertain.

Use a field from the AI’s JSON output (e.g., category, priority) as the key for an IF/switch decision in the workflow, routing each case to a different action.

This is where AI stops being decoration and becomes the brain of the automation: it classifies, and the workflow branches. Knowing how to build this bridge is what makes automation truly intelligent.

AI decides, workflow executes · categorical field as key · one branch per case + default branch.

Build a set of test cases (including difficult and adversarial cases), run the prompt against all of them, measure the accuracy rate, and adjust the prompt until it stabilizes.

A prompt that works in one example can fail in ten. Only a test cycle with real cases gives you the confidence to let AI make decisions on its own in production.

Test suite · difficult cases first · iterate until the success rate stabilizes.