​

Constants System Architecture

​

Executive Summary

• Verified Execution: Runs real code in isolated sandboxes, not approximations
• Observable + Replayable: Full run history with logs, artifacts, and reruns
• Agent-Ready: Callable via MCP, REST API, and Slack with the same contract and governance as the human UI
• Multi-Tenant: Organizations with roles, quotas, shared credentials, and team management
• AI-Powered Discovery: Scan GitHub repos to automatically discover and create tools

​

Core Primitives

​

System Architecture Overview

       Humans                 Agents                  Code               Slack
         │                      │                      │                   │
         ▼                      ▼                      ▼                   ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              Client Layer                                       │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│   │   Web UI     │  │   MCP        │  │   REST API   │  │   Slack Bot  │       │
│   │   (React)    │  │   (JSON-RPC) │  │   (V1)       │  │   (Events)   │       │
│   └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
└──────────┼─────────────────┼─────────────────┼─────────────────┼────────────────┘
           │                 │                 │                 │
           ▼                 ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                    API Layer (Next.js App Router, ~78 routes)                    │
│   ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
│   │  Workers   │ │  Agent     │ │  GitHub    │ │  Orgs &    │ │  Proxy       │ │
│   │  CRUD+Run  │ │  Chat      │ │  Scan      │ │  Auth      │ │  APIs        │ │
│   └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └──────┬───────┘ │
└─────────┼──────────────┼──────────────┼──────────────┼───────────────┼──────────┘
          │              │              │              │               │
          ▼              ▼              ▼              ▼               ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                            Services Layer                                        │
│   ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
│   │  Worker    │ │  Agent     │ │  Credential│ │  Skills    │ │  Generation  │ │
│   │  Service   │ │  Worker    │ │  Vault     │ │  Loader    │ │  Pipeline    │ │
│   └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └──────┬───────┘ │
└─────────┼──────────────┼──────────────┼──────────────┼───────────────┼──────────┘
          │              │              │              │               │
          ▼              ▼              ▼              ▼               ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                          Infrastructure Layer                                    │
│   ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
│   │ PostgreSQL │ │ E2B        │ │ Supabase   │ │ Anthropic  │ │ External     │ │
│   │ (Drizzle)  │ │ Sandboxes  │ │ Auth+Store │ │ Claude API │ │ APIs         │ │
│   └────────────┘ └────────────┘ └────────────┘ └────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────────┐
│  Agent Worker Process (standalone, polls DB)                                     │
│  Claude Agent SDK → MCP tool execution → event streaming → result persistence   │
└─────────────────────────────────────────────────────────────────────────────────┘

​

Worker Generation Pipeline

​

Phase 1: Interface Schema Generation

• inputSchema: Typed field definitions (string, number, file, directory, array) with validation
• outputSchema: Output field definitions (string, number, file, json) for result rendering
• requiredCredentials: Cloud or custom credentials needed at runtime
• computeTier: Resource allocation (cpu-2, cpu-4, cpu-8, gpu)
• pythonDependencies: Additional packages beyond the base template
• title and summary: Human-readable metadata
• actions: Interactive follow-up actions (for stateful tools)

​

Phase 2: Parallel Component Generation

​

Frontend Generation

• HTML Structure: Form inputs matching the inputSchema, including file pickers and credential selectors
• CSS Styling: Consistent design system with responsive layout
• JavaScript Logic: Form validation, file handling, result display
• Built-in components: Access to ConstantsUI library (CredentialPicker, DataTable, Chart, FilePicker, FileDownload, JsonViewer, StatCards)

• Sends WORKER_RUN with collected input data
• Receives WORKER_RESULT with execution output
• Delegates file uploads to parent via WORKER_UPLOAD

​

Backend Generation

• Reads input as JSON from stdin
• Processes data using available skills (via from constants_utils import *)
• Prints output as JSON to stdout

• Skill documentation: Relevant skills loaded based on credential requirements and detected keywords
• Project files: If provided, the agent can read and analyze existing code
• Interface schema: Ensures generated code adheres to the input/output contract

​

Phase 3: Validation & Persistence

1. Frontend compiles JSX via esbuild (if used)
2. Components are validated for correctness
3. Results submitted to /api/workers/[id]/result
4. Worker persisted with status “running”
5. Conversation history updated

​

Edit Mode

​

Security Model

• Receives a signed worker token (createWorkerRunToken)
• Anthropic calls routed through /api/proxy/claude-sdk with token validation
• Token scoped to specific user/org/worker context

​

Agent System

​

Architecture

​

Provider Abstraction

• Model: claude-sonnet-4-6
• Max turns: 25
• Conversation history embedded as XML blocks in the system prompt
• Each MCP tool mapped to a Zod-shaped SDK tool

​

Tool Execution

• listUserTools discovers available workers
• executeWorkerTool runs workers in E2B sandboxes
• Results formatted via format-result.ts

​

File Handling

• MIME type matching against accept patterns in the interface schema
• Files stored via addWorkerFile + blob storage
• If required file fields are missing, tool execution returns needsInput with missingFields metadata

​

Caller Types

​

Event Streaming

​

Sandbox Execution Model

​

E2B Sandbox Architecture

• Python 3.11+ with scientific computing stack (pandas, numpy, scipy)
• Cloud SDKs (google-cloud-*, boto3)
• Media tools (ffmpeg, Pillow)
• Build tools (gcloud, gsutil)

​

Execution Flow

1. Sandbox initialization: Create isolated sandbox with the specified compute tier
2. Skills installation: Bundle skill utilities as constants_utils package
3. File setup:
   • User uploads → /home/user/inputs/{fieldName}/
   • Output directory → /home/user/outputs/
   • Project files → /home/user/project/
   • Input data → /home/user/input.json
4. Environment configuration:
   • Platform API URL and signed worker token
   • Cloud credentials (written to files, env vars set)
   • Storage configuration
5. Code execution: python -u main.py < /home/user/input.json
6. Result extraction:
   • Parse JSON from stdout
   • Collect output files from /home/user/outputs/
   • Record uploaded files

​

Security Boundaries

• Sandbox receives a signed worker token
• Token authorizes calls to platform proxy APIs
• Proxy validates token and makes actual API calls server-side

​

Skills System

​

Architecture

​

Available Skills

​

Loading Strategy

1. Manifest level: Brief summary of all skills always included in generation prompts
2. Documentation level: Full SKILL.md loaded based on:
   • Credential requirements matching interface schema
   • Trigger keywords detected in user request
   • Services identified from project analysis
3. Shared references: Authentication guides (_shared/GCP_AUTH.md, _shared/AWS_AUTH.md) loaded when relevant skills are selected

​

Runtime Installation

1. Discovers all Python files from skill directories
2. Parses module-level function exports
3. Generates __init__.py with all exports
4. Writes to /home/user/constants_utils/ in sandbox
5. Worker code imports: from constants_utils import *

​

Credentials System

​

Architecture

​

Binding & Resolution

1. Organization binding — Credential explicitly bound to the tool at org level
2. Personal binding — Credential bound by the running user
3. Auto-match — If exactly one stored credential matches the required type
4. Runtime paste — User pastes a credential value at run time
5. Unresolved — Warning logged, field left empty

​

Dual Channel Output

• Cloud credentials (GCP service account, AWS access key, Azure): Written to files and environment variables in the sandbox
• Custom credentials (API keys, tokens): Merged into input.json under a credentials key

​

MCP Server Integration

​

Protocol Implementation

• initialize — Returns server capabilities
• tools/list — Lists available workers as tools (owned + shared)
• tools/call — Executes a worker tool
• ping — Keep-alive

​

Tool Conversion

• Sanitized tool name (title + ID suffix)
• Description from worker summary
• Input schema derived from the worker’s interface schema
• File fields excluded (not supported in MCP context)

​

Execution Flow

1. Agent sends tools/call with tool name and arguments
2. MCP server authenticates via API key
3. Worker identified by tool name suffix
4. Access verified (ownership or sharing)
5. Executed in E2B sandbox (same path as UI)
6. Run logged with triggeredBy: "agent", triggerSource: "mcp"
7. Result returned to agent

​

GitHub Scanning

​

Architecture

​

Scan Flow

1. Initiation: User triggers scan via /api/github/scan with repo URL
2. Sandbox setup: E2B sandbox created with scanner-runner.js and repo contents (zip download)
3. AI analysis: Claude agent with read-only tools (Read, Grep, Glob) explores the codebase
4. Candidate discovery: Agent outputs structured JSON with candidates (name, description, category, score)
5. Progress streaming: Events posted to scan_events table via callbacks
6. Review: User reviews candidates in the UI (ScanProgressBanner, ConnectCodebaseView)
7. Bulk creation: Selected candidates created as workers via WorkerGenerationService

​

Security

• Sandbox receives a scan token (createScanToken)
• Anthropic calls routed through /api/proxy/claude-sdk
• Token scoped to specific user/org/scan context

​

Slack Integration

​

Architecture

1. Verify Slack signature (HMAC-SHA256, 5-minute timestamp skew)
2. Handle url_verification challenge
3. On app_mention: resolve connection, post “Working on it…” message, collect thread history (last 50 messages), create agent_run with Slack callback metadata
4. Agent worker processes the run, updates the Slack message with results via Block Kit formatting

​

Queue-Based Processing

• Claims the Slack-origin agent_run
• Runs Claude Agent SDK with thread history as context
• Posts results back to Slack via chat.update or postMessage

​

Interactive Sessions

​

Architecture

• React + ReactDOM UMD bundles
• ConstantsUI component bundle (DataTable, Chart, JsonViewer, FilePicker, etc.)
• Base HTML/CSS/JS shell with loading overlay and error handling
• LLM-generated tool JS and CSS

​

Organizations

​

Architecture

• Personal org: Auto-created for each user on first API call
• Team org: Created explicitly with name, slug, avatar
• Roles: owner, admin, member, viewer — enforced via withOrgAccess middleware
• Quotas: Per-org limits on LLM, search, scrape, image, ASR, TTS usage with tier-based defaults and custom overrides
• Invite flow: Email-based invites with pending status, auto-accepted on login

​

V1 REST API

​

Architecture

​

Frontend/Backend Communication

​

The Interface Schema Contract

{
  inputSchema: {
    type: "object",
    properties: [
      { name: "query", type: "string", description: "Search query", accept: null, multiple: null },
      { name: "videoFile", type: "file", description: "Video to process", accept: [".mp4", ".mov"], multiple: false }
    ],
    required: ["query"]
  },
  outputSchema: {
    type: "object",
    properties: [
      { name: "results", type: "json", description: "Search results" },
      { name: "processedCount", type: "number", description: "Number processed" }
    ]
  },
  requiredCredentials: [
    { key: "gcp_service_account", label: "GCP Service Account", type: "textarea", instructions: "..." }
  ],
  computeTier: "cpu-4",
  pythonDependencies: { packages: ["custom-lib==1.0"] }
}

​

postMessage Protocol

{
  type: 'WORKER_RUN',
  payload: {
    query: "search term",
    videoFile: "/path/injected/by/platform",
    credentials: { gcp_service_account: "..." }
  }
}

{
  type: 'WORKER_RESULT',
  payload: {
    results: [...],
    processedCount: 42
  }
}

​

Data Flow Examples

​

Worker Creation

User Prompt (+ optional files/GitHub URL)
    ↓
Phase 1: Interface Schema Generation (Claude Agent SDK)
    ↓
Phase 2: Parallel Frontend + Backend Generation (forkSession)
    ↓
Phase 3: Validation, Compilation, Persistence
    ↓
Worker Ready (status: "running")

​

Worker Execution (UI)

Frontend iframe: WORKER_RUN postMessage
    ↓
API: /api/workers/[id]/run
    ↓
Resolve credentials (vault bindings + auto-match)
    ↓
Download input files from blob storage
    ↓
E2B Sandbox: execute python with skills + credentials
    ↓
Extract results + upload output files
    ↓
Database: log run, store outputs
    ↓
Frontend iframe: WORKER_RESULT postMessage

​

Worker Execution (Agent / MCP / V1)

Agent/MCP/V1: tool call with arguments
    ↓
Authenticate (API key or agent context)
    ↓
Resolve worker by tool name
    ↓
Verify access (ownership, sharing, or featured)
    ↓
Resolve credentials + execute in E2B Sandbox
    ↓
Log run (triggeredBy, triggerSource, callerType)
    ↓
Return result to caller

​

GitHub Repo Scan

User: connect GitHub + trigger scan
    ↓
Create repoScans record + E2B sandbox
    ↓
scanner-runner.js: Claude Agent SDK explores repo (read-only)
    ↓
Stream progress events → scan_events table
    ↓
Output: candidate list with names, descriptions, scores
    ↓
User reviews candidates in UI
    ↓
Bulk create: WorkerGenerationService per selected candidate

​

Security Boundaries

1. Sandbox isolation: No access to host system, controlled network, fresh environment per run
2. Proxy pattern: Raw API keys never reach sandboxes — signed tokens + platform proxy for all external calls
3. Credential encryption: AES-256-GCM at rest, scoped bindings, resolution chain with audit trail
4. API key security: Hashed storage, scoped permissions (mcp:read, mcp:execute), revocation support
5. Access control: Ownership + sharing + organization role verification on every operation
6. Audit trail: All runs logged with full context (caller type, trigger source, credential sources, input summary)
7. Slack verification: HMAC-SHA256 signature verification with timestamp skew protection
8. Scan tokens: Scoped, short-lived tokens for GitHub scan sandbox operations

​

Database Schema

​

Table Groups