Multi-Agent Architecture: Building SaaS

Originally published at chudi.dev

"Just ask GPT-5 to build a SaaS."

I tried. It doesn't work. Not because the model is incapable, but because the prompt space required for research, architecture, coding, and deployment is fundamentally incompatible.

Multi-agent architecture solves this.

The Problem with Single Agents

A single agent building a SaaS needs to:

• Research markets and competitors
• Validate problem severity
• Design database schemas
• Write TypeScript code
• Configure Stripe webhooks
• Deploy to Vercel

Each task requires different:

• Context: Market data vs code libraries
• Tools: Web search vs file editing
• Prompts: Business analysis vs code generation
• Evaluation: "Is this a real problem?" vs "Does this compile?"

Cramming everything into one agent causes:

• Context overflow - Too much information, model loses focus
• Prompt conflict - "Be creative" vs "Be precise" compete
• Tool confusion - When to search web vs when to write code
• Quality degradation - Jack of all trades, master of none

The Four-Agent Solution

MicroSaaSBot separates concerns into specialized agents:

[Researcher] → [Architect] → [Developer] → [Deployer]
     ↓              ↓              ↓             ↓
  Validation    Tech Stack     Features      Live URL
   Report        Document        Code        + Billing

Each agent is optimized for a single phase.

Agent 1: Researcher

Purpose: Validate whether a problem is worth solving.

Inputs:

• Problem statement from user
• Access to web search
• Competitor analysis prompts

Outputs:

• Problem score (0-100)
• Persona definition
• Competitive landscape
• Key differentiation opportunities

Specialized prompts:

You are a market researcher. Your job is to determine if a problem
is worth solving before any code is written.

Evaluate:
1. Severity (1-10): How much does this hurt?
2. Frequency (1-10): How often does it happen?
3. Willingness to pay (1-10): Are people spending money?
4. Competition (1-10): Is the market underserved?

Output a score 0-100 with reasoning.

The Researcher knows nothing about TypeScript, Vercel, or Stripe. It shouldn't.

Agent 2: Architect

Purpose: Design the technical system.

Inputs:

• Validation report from Researcher
• Tech stack preferences
• Architecture patterns library

Outputs:

• Tech stack decision
• Database schema
• API design
• Security considerations
• Deployment strategy

Specialized prompts:

You are a software architect. Design a system to solve the validated
problem. The Researcher has confirmed this is worth building.

Constraints:
- Must be deployable to Vercel serverless
- Must use Stripe for payments
- Must complete in under 1 week of development
- Prioritize simplicity over features

Output a technical specification document.

The Architect receives the Researcher's validation report but not its conversation history. Clean context, focused decisions.

Agent 3: Developer

Purpose: Write working code.

Inputs:

• Technical specification from Architect
• Codebase context
• Coding standards

Outputs:

• Feature implementations
• Tests
• Documentation
• Type definitions

Specialized prompts:

You are a senior TypeScript developer. Implement the features
specified in the architecture document.

Standards:
- TypeScript strict mode
- Error handling for all async operations
- No `any` types without justification
- Each file under 300 lines

Build features incrementally, testing each before proceeding.

The Developer doesn't question the architecture—that decision is made. It focuses entirely on clean implementation.

Agent 4: Deployer

Purpose: Ship to production.

Inputs:

• Working codebase from Developer
• Deployment configuration
• Environment variables

Outputs:

• Live URL
• Configured database
• Working billing
• Monitoring setup

Specialized prompts:

You are a DevOps engineer. Deploy the completed application to
production.

Checklist:
- Vercel project created and connected
- Supabase database provisioned with schema
- Stripe products and prices configured
- Environment variables set
- Webhooks connected
- SSL and domain configured

Output the live URL when complete.

The Deployer doesn't write features. It ships what's built.

Handoff Protocols

The critical challenge: how do agents share context without losing information?

Structured Handoff Documents

Each transition uses a defined schema:

Researcher → Architect:

interface ValidationHandoff {
  problemStatement: string;
  score: number;
  persona: {
    who: string;
    painPoints: string[];
    currentSolutions: string[];
  };
  competitors: Competitor[];
  recommendation: 'proceed' | 'kill';
  keyConstraints: string[];
}

Architect → Developer:

interface ArchitectureHandoff {
  techStack: TechStack;
  schema: DatabaseSchema;
  apiEndpoints: Endpoint[];
  features: FeatureSpec[];
  securityRequirements: string[];
  deploymentTarget: 'vercel' | 'other';
}

Developer → Deployer:

interface DeploymentHandoff {
  codebaseReady: boolean;
  buildPasses: boolean;
  envVarsNeeded: string[];
  stripeConfig: StripeConfig;
  databaseMigrations: string[];
}

Without defined schemas, agents make assumptions. The Architect might assume the Developer knows about a security requirement that was only in conversation context. Schemas force explicit communication.

Context Compression

Raw conversation history is too noisy. Handoffs include:

• Summary: Key decisions in 2-3 paragraphs
• Constraints: Non-negotiable requirements
• Artifacts: Schemas, diagrams, code snippets
• Decisions log: What was decided and why

The next agent gets a clean brief, not a transcript.

Failure Isolation

What happens when an agent fails?

Retry with Context

First attempt: retry with additional context.

Developer failed to implement PDF parsing.
Adding context: "unpdf is serverless-compatible, pdf-parse is not"
Retrying...

Most failures are context gaps, not capability limits.

Phase Rollback

Persistent failure: roll back to previous phase.

Developer failed 3 times on PDF parsing.
Rolling back to Architect for alternative approach.
Architect: "Switching to client-side PDF.js processing"
Resuming Developer phase with new approach.

The Researcher's validation isn't lost. Only the broken phase restarts.

Human Escalation

Repeated rollbacks: surface for human review.

Developer failed 3 times.
Architect revision failed 2 times.
Escalating to human review with full context.

The human sees exactly what went wrong, not a generic error.

Phase Gates

Agents can't proceed until quality criteria are met:

Researcher Gate:

• Score above 60
• Persona clearly defined
• At least 3 competitors analyzed

Architect Gate:

• All features have specified approach
• Database schema is complete
• Security requirements documented

Developer Gate:

• Build passes (pnpm build)
• Types compile (tsc --noEmit)
• Core features functional

Deployer Gate:

• Live URL accessible
• Auth flow works
• Payment flow works

Gates are enforced. A Developer that says "should work" doesn't pass the build gate. Evidence required.

The Result

MicroSaaSBot's architecture enables:

Single-agent systems can't match this. The complexity of product development requires divided attention—literally.

Lessons Learned

1. Specialization > Generalization - Four focused agents outperform one omniscient agent
2. Schemas prevent drift - Define handoff formats explicitly
3. Gates enforce quality - Don't trust "should work"
4. Failure is expected - Design for retry and rollback
5. Humans are fallback - Not replacements, but escalation targets

Multi-agent architecture isn't just an implementation detail. It's what makes complex AI systems reliable.

Related: Introducing MicroSaaSBot | Portfolio: MicroSaaSBot