Solution Design Process

Trigger: Discovery notes finalized in Notion + scope confirmed by client Owner: Assigned dev partner (builder) Output: Solution design document in Notion — completed before any build begins

Anything touching more than 2 systems, involving AI processing, or requiring conditional logic must be designed before building. A 30-minute design document prevents a 3-day rebuild.

Solution Design Document Template

SOLUTION DESIGN — [Client Name] — [Automation Name]
────────────────────────────────────────────────────
Date: | Builder: | Reviewer:

1. TRIGGER
   What event starts this automation:
   Type: [Webhook / Schedule / Manual / Form / API event]
   Source system: [Name]

2. PROCESS FLOW
   Step 1: [Action] — [Tool/System]
   Step 2: [Action] — [Tool/System]
   Step 3: [Decision — if X then Y, else Z]
   Step 4: [Action] — [Tool/System]

3. AI COMPONENTS (if any)
   What AI does: [classify / extract / generate / summarise]
   Model: [Claude 3.5 Sonnet / GPT-4o / other]
   Input: [what data is sent to the model]
   Output: [expected format and content]
   Prompt strategy: [see AI Integration Standards]
   Fallback if AI fails: [specific action]

4. SYSTEMS & INTEGRATIONS
   System  | Action     | Auth method | Status
   --------|------------|-------------|------------------
   [Name]  | Read/Write | API key     | ✅ Have access
   [Name]  | Read       | OAuth       | 🟡 Pending

5. DATA MAPPING
   From [Field] in [System] → To [Field] in [System]
   Transformation needed: [yes/no — describe if yes]

6. ERROR HANDLING PLAN
   Step [X] fails → [specific action]
   AI returns unexpected output → [fallback]
   System unavailable → [retry / alert / stop]

7. EDGE CASES
   Scenario: [X] → Handled by: [Y]
   Scenario: [X] → Handled by: [Y]

8. TEST PLAN
   Test 1: [input] → [expected output]
   Test 2: [edge case] → [expected behaviour]
   Test 3: [error scenario] → [expected behaviour]

9. DEPLOYMENT NOTES
   Platform: [n8n / Make / custom code]
   Hosting: [TBD per project requirements]
   Environment variables required: [list]

10. OPEN QUESTIONS (resolve before build starts)
    •
    •
────────────────────────────────────────────────────

PMO partner reviews and approves the solution design before any build begins. If the design reveals scope changes, update the client scope confirmation before proceeding.

Platform & Hosting Decisions

Hosting decisions are made per project — no single default. Decision must be documented and justified.

Decision Framework

FactorConsideration
Client has existing infrastructureDeploy there where possible
Data sensitivity (PII, financial)Prefer client-hosted or dedicated — avoid shared cloud
High execution volumeSelf-hosted n8n on VPS or custom code
Speed to delivern8n Cloud or Make cloud is fastest
Client manages it themselves post-retainerChoose the simplest platform

Supported Options

  • n8n Cloud — managed, fastest to deploy
  • n8n self-hosted on AWS EC2 or VPS
  • Make (cloud — Integromat infrastructure)
  • AWS Lambda / EC2 for custom code components
  • Client’s own infrastructure when required

Document the choice and reasoning in GitHub README + Notion solution design.