---
title: Deployment Architecture
description: Zero-config web app deployments powered by Vercel
---

## Overview

InsForge Deployments enable developers to deploy web applications with a single prompt. By integrating with coding agents via InsForge MCP, developers can simply say "Deploy my app" and have their application live within a minute—no configuration required.

## Technology Stack

```mermaid
graph TB
    Agent[Coding Agent] --> MCP[InsForge MCP]
    MCP --> API[InsForge Server]

    API --> S3[AWS S3 Legacy Zip Upload]
    API --> VercelFiles[Vercel File Upload API]
    S3 --> API
    VercelFiles --> Vercel[Vercel Build Platform]

    API --> DB[(PostgreSQL)]
    DB --> Manifest[Deployment Manifest]
    DB --> Metadata[Deployment Metadata]
    DB --> Status[Status Tracking]

    Vercel --> Live[Live Application]

    style Agent fill:#1e293b,stroke:#475569,color:#e2e8f0
    style MCP fill:#1e40af,stroke:#3b82f6,color:#dbeafe
    style API fill:#166534,stroke:#22c55e,color:#dcfce7
    style S3 fill:#ea580c,stroke:#f97316,color:#fed7aa
    style VercelFiles fill:#111827,stroke:#9ca3af,color:#f9fafb
    style Vercel fill:#000000,stroke:#ffffff,color:#ffffff
    style DB fill:#0e7490,stroke:#06b6d4,color:#cffafe
    style Manifest fill:#0e7490,stroke:#22d3ee,color:#cffafe
    style Metadata fill:#0e7490,stroke:#22d3ee,color:#cffafe
    style Status fill:#0e7490,stroke:#22d3ee,color:#cffafe
    style Live fill:#166534,stroke:#22c55e,color:#dcfce7
```

## Core Components

| Component | Technology | Purpose |
|-----------|------------|---------|
| **Legacy Uploads** | AWS S3 | Backward-compatible source zip staging |
| **Upload Proxy** | Express streaming endpoint | Upload files to Vercel without exposing provider credentials |
| **Build Platform** | Vercel | Production builds and hosting |
| **Status Tracking** | PostgreSQL | Deployment state, direct-upload manifest, and metadata |
| **Webhook Handler** | HMAC-SHA1 | Real-time build status updates |

## How It Works

### Deployment Flow

```mermaid
sequenceDiagram
    participant Agent as Coding Agent
    participant API as InsForge Server
    participant DB as PostgreSQL
    participant Vercel as Vercel

    Agent->>API: Create direct deployment with file manifest
    API->>DB: Store path, SHA, and size for each file
    API-->>Agent: Deployment ID

    API-->>Agent: Deployment ID + file IDs

    loop Files, with bounded client concurrency
        Agent->>API: Stream one file by file ID
        API->>Vercel: Stream file to /v2/files
        API->>DB: Mark file uploaded
    end

    Agent->>API: Start deployment
    API->>DB: Verify all files uploaded
    API->>Vercel: Create deployment with uploaded file SHAs
    API-->>Agent: Deployment started

    Vercel->>Vercel: Build application
    Vercel->>API: Webhook: Build complete

    Agent->>API: Check status
    API-->>Agent: READY + live URL
```

### Step-by-Step Process

#### Direct Upload Flow

1. **Create Deployment**: Agent calls `POST /api/deployments/direct` with each relative file path, SHA-1 digest, and byte size; InsForge stores the manifest and returns a deployment ID plus a file ID for each manifest entry
2. **Upload Files**: Agent streams each file to `PUT /api/deployments/:id/files/:fileId/content` using bounded client-side concurrency; InsForge validates bytes against the manifest and forwards the stream to Vercel without exposing Vercel credentials
3. **Retry If Needed**: If an upload is interrupted, the agent can retry individual file uploads for the same deployment ID. To inspect progress, query `deployments.files` with a raw SQL tool for that `deployment_id`
4. **Start Build**: Agent calls `POST /api/deployments/:id/start`; InsForge verifies every manifest file was uploaded, then creates the Vercel deployment with uploaded file SHAs
5. **Build & Deploy**: Vercel builds the application and deploys to its edge network
6. **Go Live**: Application becomes available at `https://{app-key}.insforge.site`

#### Legacy Zip Flow

1. **Create Deployment**: Agent calls `POST /api/deployments` and receives a presigned S3 upload URL
2. **Upload Source Zip**: Agent uploads a zip archive to S3
3. **Start Build**: InsForge downloads the zip, extracts source files, uploads them to Vercel, and creates the deployment
4. **Build & Deploy**: Vercel builds the application and deploys to its edge network
5. **Go Live**: Application becomes available at `https://{app-key}.insforge.site`

The entire process typically completes in about one minute.

## Deployment Status

| Status | Description |
|--------|-------------|
| `WAITING` | Deployment created, awaiting source zip upload or direct file uploads |
| `UPLOADING` | Source files are being proxied to Vercel or deployment creation is in progress |
| `QUEUED` | Build queued on Vercel |
| `BUILDING` | Application being built |
| `READY` | Live and accessible |
| `ERROR` | Build failed |
| `CANCELED` | Deployment canceled |

## Environment Variables

Environment variables can be passed during deployment for build-time configuration. They are encrypted at rest and in transit, and are only accessible during the build process. For auditing purposes, only variable names are logged, never values.

<Warning>
  While environment variables are encrypted, avoid storing sensitive credentials in frontend applications. Variables prefixed with `NEXT_PUBLIC_` or similar are embedded in client bundles.
</Warning>

## Current Limitations

<Note>
  Deployments currently has the following constraints:
</Note>

| Limitation | Details |
|------------|---------|
| **Environment** | Production deployments only |
| **Custom Domains** | Coming soon |
| **Preview Deployments** | Coming soon |
| **Build Logs** | Limited visibility |

## Performance

### Direct Upload Optimization

Deployment uploads stream through InsForge directly into Vercel's file upload API, enabling:

- **Lower Memory Use**: Source zips are no longer buffered and unzipped by the backend for direct-capable clients
- **Credential Safety**: Vercel credentials remain server-side while clients upload individual files
- **Compatibility**: Existing zip/S3 clients can continue using the legacy deployment entrypoint
- **Rapid Builds**: Vercel's distributed build infrastructure
- **Global Distribution**: Deployed applications served from edge locations worldwide
- **Low Latency**: Sub-100ms response times for static assets

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep Builds Small" icon="minimize">
    Avoid uploading large assets. Use InsForge Storage and access via URLs.
  </Card>

  <Card title="Use Environment Variables" icon="key">
    Configure builds via env vars, not hardcoded values
  </Card>

  <Card title="Test Locally First" icon="flask">
    Verify builds work locally before deploying
  </Card>

  <Card title="Monitor Status" icon="chart-line">
    Check deployment status for build errors
  </Card>
</CardGroup>
