Architecture Overview

MicroBuilder's architecture is designed for reliability, scalability, and deterministic app generation. This document explains the core systems and design decisions.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                         User Interface                       │
│  (Next.js 15 App Router + React + Tailwind)                 │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────────┐
│                    API Layer (Express)                       │
│  • Authentication      • Build Management                    │
│  • Integration APIs    • Webhook Handlers                    │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────────┐
│                  AI Planning & Routing                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Planner    │  │  Capability  │  │   Validator  │      │
│  │ (Claude, T=0)│  │    Matrix    │  │  (Claude)    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────────┐
│              Deterministic Build Engine                      │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Component Registry (Verified Modules)               │   │
│  │  • Backend Components (T=0)                          │   │
│  │  • Frontend Components (T=0.5-0.8 for styling)      │   │
│  │  • Integration Modules (Cryptographically Signed)   │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────────┐
│                  Assembly & Generation                       │
│  • Database Schema    • API Endpoints                        │
│  • Auth Flows        • UI Components                         │
│  • Integration Wiring • Testing                              │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────────┐
│                   Infrastructure Layer                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │PostgreSQL│  │  Supabase│  │  Vercel  │  │  CDN     │   │
│  │(Supabase)│  │  Storage │  │   Edge   │  │          │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘

Core Components

1. AI Planning Layer

Purpose: Analyze user requirements and create build specifications

Models Used:

Planner: Anthropic Claude (temperature=0)
Code Generator: OpenAI GPT-4 / Claude (temperature=0 for backend)
Styler: GPT-4 (temperature=0.5-0.8 for frontend aesthetics)

Process:

Parse natural language input
Extract functional requirements
Identify needed integrations
Plan database schema
Design system architecture
Generate build specification

Output: Structured JSON specification for deterministic assembly

2. Capability Matrix

Purpose: Smart routing and integration selection

How It Works:

interface CapabilityMatrix {
  integrations: Map<Integration, Capability[]>;
  requirements: Requirement[];
  
  select(): {
    primary: Integration[],
    fallback: Integration[],
    unsupported: Requirement[]
  }
}

Features:

Automatic integration selection
Partial feature support (Hybrid Assembly Mode)
Graceful degradation
Alternative routing

Example:

User wants: "Send emails with attachments"

Matrix evaluates:
- Resend: ✅ Email, ❌ Attachments
- Twilio SendGrid: ✅ Email, ✅ Attachments
- SMTP: ✅ Email, ✅ Attachments

Selection: Twilio SendGrid (full support)
Fallback: SMTP (if SendGrid fails)

Learn More →

3. Component Registry

Purpose: Pre-built, verified components for deterministic assembly

Structure:

components/
  ├── auth/
  │   ├── supabase-oauth.ts       (Google + GitHub)
  │   ├── session-management.ts
  │   └── protected-routes.ts
  ├── database/
  │   ├── user-schema.ts
  │   ├── migrations/
  │   └── queries/
  ├── integrations/
  │   ├── stripe-checkout.ts
  │   ├── openai-chat.ts
  │   └── twilio-sms.ts
  └── ui/
      ├── dashboard.tsx
      ├── forms.tsx
      └── tables.tsx

Verification:

Cryptographically signed (RSA-SHA256)
Integrity checked (SHA-256 hashes)
Forbidden API detection
Test coverage >80%

Learn More →

4. Deterministic Build Engine

Purpose: Generate consistent, production-ready code

Temperature Settings:

Backend Logic: 0 (completely deterministic)
Database Schemas: 0 (no variation)
API Endpoints: 0 (consistent patterns)
Frontend Styling: 0.5-0.8 (controlled creativity)

Why Deterministic?

Same inputs → Same outputs
Reproducible builds
Predictable behavior
Easier debugging
Production reliability

Learn More →

5. Hybrid Assembly Mode

Purpose: Handle partial feature support gracefully

Modes:

Full Support: All features available
Partial Support: Some features via alternative methods
Degraded: Core features only
Unsupported: Clear error messages

Example:

User wants: Analytics dashboard with charts

Full Mode:
- Use Chart.js for visualization
- Real-time data updates
- Export to PDF

Partial Mode:
- Use simple tables instead of charts
- Manual data refresh
- Export to CSV (not PDF)

Degraded Mode:
- Display data in lists
- No exports
- Clear "upgrade to Pro" messaging

Learn More →

Data Flow

Build Request Flow

1. User Input
   "Build a task management app with Slack notifications"
   
2. AI Planning
   → Parse requirements
   → Identify: Database, Auth, Slack integration
   → Plan architecture
   
3. Capability Matrix
   → Check Slack integration available
   → Verify database setup possible
   → Confirm auth providers configured
   
4. Component Selection
   → Select: PostgreSQL schema templates
   → Select: Supabase auth components
   → Select: Slack notification module
   
5. Deterministic Assembly
   → Generate database schema (T=0)
   → Create API endpoints (T=0)
   → Build UI components (T=0.6 for styling)
   → Wire Slack integration
   
6. Testing & Validation
   → Run integration tests
   → Verify database migrations
   → Check API connectivity
   
7. Deployment
   → Build optimized bundle
   → Deploy to Vercel Edge
   → Configure CDN
   → Enable monitoring

Live Editing Flow

1. User Request
   "Change the dashboard theme to purple"
   
2. Contextual Analysis
   → Load current app state
   → Identify affected components
   → Check theme system
   
3. Incremental Update
   → Update Tailwind config
   → Modify component styles
   → Preserve functionality
   
4. Hot Reload
   → Apply changes instantly
   → No full rebuild needed
   → Maintain user session

Security Architecture

Defense in Depth

Layer 1: Network Security

HTTPS/TLS encryption
DDoS protection (Vercel)
Rate limiting
IP whitelisting (optional)

Layer 2: Application Security

Input validation
SQL injection prevention (Drizzle ORM)
XSS protection
CSRF tokens

Layer 3: Authentication

OAuth 2.0 (Google, GitHub)
Supabase Auth
Session management
JWT tokens

Layer 4: Authorization

Role-based access control (RBAC)
Resource-level permissions
API key scoping

Layer 5: Data Security

Encryption at rest (database)
Encryption in transit (TLS)
Secret management (environment variables)
Key rotation

Layer 6: Code Security

Cryptographic module signing
Integrity verification
Forbidden API detection
Sandbox execution

Learn More →

Scalability

Horizontal Scaling

Stateless Architecture:

No server-side session state
JWT-based authentication
Cached database queries
CDN for static assets

Auto-Scaling:

Vercel Edge Functions (serverless)
Database connection pooling (Supabase)
Redis caching (optional)

Database Optimization

Strategies:

Connection pooling
Query optimization
Index management
Read replicas (Pro/Branded plans)

Performance

Targets:

Page load: <2s (first paint)
API response: <200ms (p95)
Build time: <5min (average app)
Deploy time: <2min

Technology Choices

Why Next.js 15?

Server components (performance)
App Router (modern routing)
Server actions (simplified APIs)
Built-in optimization

Why PostgreSQL?

ACID compliance
Rich data types
Full-text search
JSON support
Battle-tested

Why Drizzle ORM?

Type-safe queries
Minimal overhead
Great TypeScript support
Migration management

Why Supabase Auth?

OAuth out-of-box
Row-level security (RLS)
Email/password auth
Magic links
2FA support

Why Vercel?

Edge network
Zero-config deployment
Automatic HTTPS
Preview deployments
Great DX

Monitoring & Observability

Metrics Tracked

Build success rate
API response times
Error rates
Integration health
User sessions

Tools

Error Tracking: Sentry
Analytics: PostHog
Logs: Vercel logs
APM: Custom dashboards

Next Steps

Questions? Contact Support

overview

Architecture Overview

System Architecture

Core Components

1. AI Planning Layer

2. Capability Matrix

3. Component Registry

4. Deterministic Build Engine

5. Hybrid Assembly Mode

Data Flow

Build Request Flow

Live Editing Flow

Security Architecture

Defense in Depth

Scalability

Horizontal Scaling

Database Optimization

Performance

Technology Choices

Why Next.js 15?

Why PostgreSQL?

Why Drizzle ORM?

Why Supabase Auth?

Why Vercel?

Monitoring & Observability

Metrics Tracked

Tools

Next Steps