🤖 Agent and n8n Integration Architecture (Post-MVP Vision)¶
Scope: POST-MVP ONLY - This is a FUTURE architecture, NOT for MVP Status: Vision / Archived (Superseded by simplified-mvp-architecture.md) Date Moved to Vision: 2025-10-13 Purpose: Documents potential future AI agent integration if we add AI post-MVP
Important Note¶
THIS IS NOT THE MVP ARCHITECTURE. The MVP uses deterministic, rule-based processing with no AI agents (see ../05-architecture/simplified-mvp-architecture.md).
This document describes a potential future architecture if we decide to add AI agents post-MVP based on customer demand and revenue to support the infrastructure.
Future Vision: How AI Agents Could Integrate¶
If we add AI agents post-MVP, this is how deterministic automation (n8n) and AI reasoning (LangGraph) could work together:
Overview¶
GetCimple uses a two-layer architecture:
- n8n: Handles deterministic automation, routing, and scheduling
- LangGraph Agent: Provides AI-powered reasoning and complex workflows
This separation ensures reliability, scalability, and clear responsibilities.
High-Level Architecture¶
┌─────────────────────────────────────────────────────────────────┐
│ User Interactions │
├────────────────┬────────────────┬────────────────┬──────────────┤
│ WhatsApp │ Web App │ Email │ Slack │
└───────┬────────┴────────┬───────┴────────┬───────┴──────┬───────┘
│ │ │ │
└────────┬────────┘ └──────┬───────┘
│ │
┌────────▼─────────────────────────────────▼────────┐
│ n8n Workflows │
│ ┌─────────────────────────────────────────────┐ │
│ │ Deterministic Automation Layer: │ │
│ │ • Message routing & formatting │ │
│ │ • Schedule triggers (daily checks) │ │
│ │ • Simple notifications │ │
│ │ • Webhook handling │ │
│ │ • API orchestration │ │
│ └─────────────────────────────────────────────┘ │
└────────────────────┬───────────────────────────────┘
│ HTTP/REST
▼
┌───────────────────────┐
│ Cloudflare Workers │ (Auth, Rate Limit)
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ GetCimple Agent │
│ (LangGraph) │
│ ┌─────────────────┐ │
│ │ AI Reasoning: │ │
│ │ • Assessments │ │
│ │ • Q&A │ │
│ │ • Reports │ │
│ │ • Extraction │ │
│ └─────────────────┘ │
└───────────┬───────────┘
│
┌────────▼────────┐
│ Supabase │
│ (Database) │
└─────────────────┘
Detailed Component Architecture¶
┌─────────────────────────────────────────────────────────────────────────┐
│ External Users │
├──────────────┬──────────────┬──────────────┬──────────────┬────────────┤
│ WhatsApp │ Web App │ Slack │ Email │ API │
└──────┬───────┴──────┬───────┴──────┬───────┴──────┬───────┴─────┬──────┘
│ │ │ │ │
│ ┌────▼────┐ │ │ │
│ │SvelteKit│ │ │ │
│ │ (ag-ui) │ │ │ │
│ └────┬────┘ │ │ │
│ │ │ │ │
└──────┬───────┴───────┬──────┴────┬─────────┘ │
│ │ │ │
┌─────────▼──────┐ ┌─────▼───────────▼─────┐ ┌─────────▼────────┐
│ n8n Container │ │ Cloudflare Workers │ │ Direct API Call │
│ (Docker/VPS) │ │ (Edge Gateway) │ │ (Authenticated) │
│ │ │ │ │ │
│ ┌────────────┐ │ │ • Auth (Kinde) │ └─────────┬────────┘
│ │ Workflows: │ │ │ • Rate Limiting │ │
│ │ │ │ │ • Request Routing │ │
│ │ • WhatsApp │ │ │ • CORS │ │
│ │ • Slack │ │ └──────────┬───────────┘ │
│ │ • Cron │ │ │ │
│ │ • Webhooks │ │ └────────────┬───────────────┘
│ └──────┬─────┘ │ │
└────────┼───────┘ │
│ HTTP │ HTTPS
└─────────────┬───────────────────┘
│
┌─────────▼──────────────────────────────────┐
│ Fly.io Container │
│ ┌─────────────────────────────────────┐ │
│ │ FastAPI Application │ │
│ │ ┌───────────────────────────────┐ │ │
│ │ │ LangGraph Agent Core │ │ │
│ │ │ ┌─────────────────────────┐ │ │ │
│ │ │ │ Workflow Components: │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ • ComplianceWorkflow │ │ │ │
│ │ │ │ • QuestionWorkflow │ │ │ │
│ │ │ │ • ReportWorkflow │ │ │ │
│ │ │ │ • ExtractionWorkflow │ │ │ │
│ │ │ └─────────┬───────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌─────────▼───────────────┐ │ │ │
│ │ │ │ Pydantic AI Layer │ │ │ │
│ │ │ │ ┌─────────────────┐ │ │ │ │
│ │ │ │ │ Type Validation │ │ │ │ │
│ │ │ │ │ • Request DTOs │ │ │ │ │
│ │ │ │ │ • Response DTOs │ │ │ │ │
│ │ │ │ │ • State Objects │ │ │ │ │
│ │ │ │ └─────────────────┘ │ │ │ │
│ │ │ └─────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ ┌───────────────────────┐ │ │ │
│ │ │ │ LLM Integration │ │ │ │
│ │ │ │ (Claude/OpenAI) │ │ │ │
│ │ │ └───────────────────────┘ │ │ │
│ │ └───────────────────────────────┘ │ │
│ │ │ │
│ │ FastAPI Routes: │ │
│ │ POST /api/agent/assess │ │
│ │ POST /api/agent/question │ │
│ │ POST /api/agent/report │ │
│ │ POST /api/agent/extract │ │
│ └─────────────────────────────────────┘ │
│ │
│ Dependencies: (installed via uv) │
│ • langgraph==0.0.28 │
│ • pydantic-ai==0.0.3 │
│ • fastapi==0.104.1 │
│ • anthropic==0.18.1 │
└────────────────────┬───────────────────────┘
│
┌───────────▼────────────┐
│ Supabase Postgres │
│ ┌─────────────────┐ │
│ │ • Agent State │ │
│ │ • Audit Logs │ │
│ │ • Compliance │ │
│ │ • Multi-tenant │ │
│ └─────────────────┘ │
└────────────────────────┘
Responsibility Matrix¶
┌─────────────────────┬──────────────────┬────────────────────┐
│ Capability │ n8n Handles │ Agent Handles │
├─────────────────────┼──────────────────┼────────────────────┤
│ Message Routing │ ✓ │ │
│ Schedule/Cron │ ✓ │ │
│ Webhooks │ ✓ │ │
│ Simple Alerts │ ✓ │ │
│ API Integration │ ✓ │ │
├─────────────────────┼──────────────────┼────────────────────┤
│ Compliance Logic │ │ ✓ │
│ Question Analysis │ │ ✓ │
│ Report Generation │ │ ✓ │
│ Risk Assessment │ │ ✓ │
│ Policy Extraction │ │ ✓ │
└─────────────────────┴──────────────────┴────────────────────┘
Request Flow Example¶
sequenceDiagram
participant W as WhatsApp User
participant N as n8n
participant C as Cloudflare
participant A as LangGraph Agent
participant D as Database
W->>N: "What's our Essential Eight status?"
Note over N: Parse message<br/>Extract tenant
N->>C: POST /api/agent/assess
C->>C: Verify auth
C->>A: Forward request
Note over A: Route to workflow<br/>Load context<br/>Run assessment
A->>D: Get compliance data
D->>A: Return data
Note over A: Apply rules<br/>Generate insight
A->>C: JSON response
C->>N: Forward response
Note over N: Format for WhatsApp
N->>W: "Essential Eight Status: ML2 85% ⚠️<br/>3 gaps need attention..."Integration Points¶
n8n to Agent API Calls¶
n8n Workflow Nodes Agent API Endpoints
───────────────── ──────────────────
HTTP Request Node ────→ POST /api/agent/assess
{ {
"url": "{{API}}/assess", "type": "compliance_check",
"body": { "tenant_id": "abc123",
"tenant": "{{tenant}}", "frameworks": ["e8"],
"type": "compliance" "context": {...}
} }
}
HTTP Request Node ────→ POST /api/agent/question
{ {
"url": "{{API}}/question", "question": "What is MFA?",
"body": { "tenant_id": "abc123",
"q": "{{message}}", "history": [...]
"tenant": "{{tenant}}" }
}
}
HTTP Request Node ────→ POST /api/agent/report
{ {
"url": "{{API}}/report", "type": "board_quarterly",
"body": { "tenant_id": "abc123",
"type": "board", "period": "Q1-2025"
"period": "Q1" }
}
}
WhatsApp Integration Flow¶
User types in WhatsApp: "Check our compliance"
│
▼
┌──────────────────────────────────────────────┐
│ n8n: WhatsApp Webhook Trigger │
│ • Extracts: phone number, message, timestamp │
└────────────────────┬─────────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ n8n: Tenant Lookup Node │
│ • Query DB for tenant by phone │
│ • Get user context │
└────────────────────┬─────────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ n8n: Route by Keywords │
│ • "compliance" → /api/agent/assess │
│ • "report" → /api/agent/report │
│ • Question → /api/agent/question │
└────────────────────┬─────────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ n8n: HTTP Request to Agent │
│ • Add auth headers │
│ • Include tenant context │
│ • Set timeout (30s) │
└────────────────────┬─────────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ LangGraph Agent Processing │
│ • Understand intent │
│ • Execute workflow │
│ • Generate response │
└────────────────────┬─────────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ n8n: Format Response │
│ • Convert JSON to WhatsApp format │
│ • Add emojis for status │
│ • Truncate if > 1600 chars │
└────────────────────┬─────────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ n8n: Send WhatsApp Reply │
│ • Via Twilio API │
│ • Track delivery status │
└──────────────────────────────────────────────┘
LangGraph and Pydantic Integration¶
┌─────────────────────────────────────────────────────────────┐
│ Incoming Request │
│ (from n8n or API) │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Endpoint │
│ @app.post("/api/agent/assess") │
│ async def assess_compliance( │
│ request: ComplianceRequest # ← Pydantic Model │
│ ) -> ComplianceResponse: # ← Pydantic Model │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Pydantic AI Validation Layer │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ class ComplianceRequest(BaseModel): │ │
│ │ tenant_id: UUID │ │
│ │ assessment_type: Literal["e8", "iso", "risk"] │ │
│ │ context: Dict[str, Any] │ │
│ │ include_evidence: bool = True │ │
│ │ │ │
│ │ @validator('tenant_id') │ │
│ │ def validate_tenant(cls, v): │ │
│ │ # Check tenant exists & authorized │ │
│ │ return v │ │
│ └─────────────────────────────────────────────────────┘ │
└───────────────────────┬─────────────────────────────────────┘
│ Validated & Typed
▼
┌─────────────────────────────────────────────────────────────┐
│ LangGraph Workflow │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ workflow = StateGraph(ComplianceState) │ │
│ │ │ │
│ │ # Define state with Pydantic │ │
│ │ class ComplianceState(BaseModel): │ │
│ │ request: ComplianceRequest │ │
│ │ current_step: str │ │
│ │ evidence: List[Evidence] │ │
│ │ scores: Dict[str, float] │ │
│ │ reasoning: List[ReasoningStep] │ │
│ │ │ │
│ │ # Workflow nodes │ │
│ │ workflow.add_node("validate", validate_input) │ │
│ │ workflow.add_node("gather", gather_evidence) │ │
│ │ workflow.add_node("assess", run_assessment) │ │
│ │ workflow.add_node("report", generate_report) │ │
│ └─────────────────────────────────────────────────────┘ │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LLM Integration │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ # Only called when needed │ │
│ │ async def interpret_ambiguous_requirement( │ │
│ │ requirement: str, │ │
│ │ context: AssessmentContext # Pydantic │ │
│ │ ) -> Interpretation: # Pydantic │ │
│ │ response = await llm.complete( │ │
│ │ prompt=ASSESSMENT_PROMPT, │ │
│ │ context=context.dict() │ │
│ │ ) │ │
│ │ return Interpretation.parse_obj(response) │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Data Type Flow¶
┌──────────────────────────────────────────────────────┐
│ n8n Workflow (JavaScript) │
│ │
│ const requestBody = { │
│ tenant_id: msg.extractedTenantId, │
│ assessment_type: "e8", │
│ context: { │
│ message: msg.whatsappText, │
│ user_phone: msg.from │
│ } │
│ } │
└────────────────────┬─────────────────────────────────┘
│ JSON over HTTP
▼
┌──────────────────────────────────────────────────────┐
│ FastAPI + Pydantic (Python) │
│ │
│ class ComplianceRequest(BaseModel): │
│ tenant_id: UUID │
│ assessment_type: AssessmentType │
│ context: Dict[str, Any] │
│ │
│ class Config: │
│ json_schema_extra = { │
│ "example": { │
│ "tenant_id": "123e4567-...", │
│ "assessment_type": "e8", │
│ "context": {...} │
│ } │
│ } │
└────────────────────┬─────────────────────────────────┘
│ Typed Python Objects
▼
┌──────────────────────────────────────────────────────┐
│ LangGraph State (Pydantic Models) │
│ │
│ class ComplianceState(BaseModel): │
│ request: ComplianceRequest │
│ current_step: WorkflowStep │
│ evidence: List[Evidence] │
│ scores: Dict[Framework, Score] │
│ reasoning: List[ReasoningStep] │
│ final_output: Optional[ComplianceResponse] │
│ │
│ def next_step(self) -> WorkflowStep: │
│ """Determine next workflow step""" │
│ ... │
└──────────────────────────────────────────────────────┘
Component Deployment¶
┌─────────────────────────────────────────────────────────┐
│ Infrastructure │
├─────────────────┬────────────────┬──────────────────────┤
│ n8n (VPS) │ Agent (Fly) │ Gateway (CF) │
│ │ │ │
│ ┌─────────────┐ │ ┌────────────┐ │ ┌─────────────────┐ │
│ │ Ubuntu 22 │ │ │ Container │ │ │ Workers Script │ │
│ │ Docker │ │ │ Python 3.11│ │ │ TypeScript │ │
│ │ n8n:latest │ │ │ uv package │ │ │ Wrangler deploy │ │
│ └─────────────┘ │ └────────────┘ │ └─────────────────┘ │
│ │ │ │
│ Resources: │ Resources: │ Resources: │
│ • 2 vCPU │ • 4 vCPU │ • 10ms CPU │
│ • 4GB RAM │ • 8GB RAM │ • 128MB RAM │
│ • 20GB SSD │ • 10GB volume │ • Global Edge │
│ │ • Multi-region│ │
└─────────────────┴────────────────┴──────────────────────┘
Managed by: Pulumi (Infrastructure as Code)
Communication Flow Example¶
Essential Eight Assessment via WhatsApp¶
User Request: "Show me BuildCo compliance status"
│
▼
WhatsApp ──→ n8n ──→ Workers
│
▼
┌─────────────────────┐
│ GetCimple Agent │
│ │
│ 1. Route Request │
│ ↓ │
│ 2. Load Context │
│ ↓ │
│ 3. Check Cache │ ← Deterministic
│ ↓ │
│ 4. Apply Essential Eight Rules │ ← Deterministic
│ ↓ │
│ 5. LLM for Gaps │ ← Only if needed
│ ↓ │
│ 6. Format Response │ ← Template-based
└─────────────────────┘
│
▼
"BuildCo Compliance Status:
Core Frameworks:
[E8] ML2 (85%) ⚠️
[S180] 2 items need board review ❌
[Privacy] Compliant ✅
[ACSC] Following guidelines ✅
3 gaps need attention:
1. MFA not enforced [E8] [S180]
2. Patch cycle > 30 days [E8]
3. Privacy policy review overdue [Privacy] [S180]"
Key Design Decisions¶
Why Separate n8n and LangGraph?¶
- Reliability: n8n handles deterministic tasks that must always work
- Cost: Only use expensive LLM calls when truly needed
- Debugging: Clear separation makes issues easier to trace
- Scaling: Can scale n8n and agent independently
- Flexibility: Easy to swap AI providers or upgrade agent logic
Why Pydantic AI?¶
- Type Safety: Catch errors before they reach production
- Documentation: Auto-generated API docs from models
- Validation: Business rules enforced at boundaries
- Compliance: Audit trail needs structured data
Why This Architecture?¶
- Simple for MVP: Just two main services to manage
- Clear boundaries: Everyone knows what each component does
- Easy to evolve: Can add agents or workflows independently
- Cost effective: Minimal infrastructure for maximum value
Implementation Checklist¶
- Deploy n8n container with basic workflows
- Set up FastAPI with LangGraph on Fly.io
- Configure Cloudflare Workers gateway
- Create Pydantic models for all data types
- Implement the 4 core agent workflows
- Connect n8n to agent via HTTP
- Test WhatsApp integration end-to-end
- Add monitoring and error handling
- Document n8n workflow templates
- Create runbooks for common issues
Related Documents: