Add Nextra SaaS platform architecture document
Comprehensive design doc covering: - System overview and architecture diagrams - Tier model (Free/Paid/Pro/Enterprise) - Component architecture (Next.js, FastAPI, Pump containers) - Database schema (PostgreSQL) - Trigger system (webhooks, schedules, manual) - Security model (tenant isolation, WASM sandboxing, memory safety) - Canvas ↔ YAML synchronization - Marketplace design - Monitoring and observability - Scaling considerations - Implementation phases Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
dullfig
parent
515c738abb
commit
2d05fd3656
1 changed files with 759 additions and 0 deletions
759
docs/nextra-architecture.md
Normal file
759
docs/nextra-architecture.md
Normal file
|
|
@ -0,0 +1,759 @@
|
|||
# Nextra SaaS Platform — Architecture Design Document
|
||||
|
||||
**Version:** 1.0 (Draft)
|
||||
**Date:** January 2026
|
||||
**Status:** Planning
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Nextra is a SaaS platform for building AI agent workflows using the xml-pipeline library. Users visually design message flows on a canvas, which generates the underlying YAML configuration. Flows run on isolated container instances with support for built-in tools, marketplace components, and custom WASM modules.
|
||||
|
||||
### Key Differentiators
|
||||
|
||||
- **Visual flow builder** with real-time YAML synchronization
|
||||
- **Turing-complete** message routing (self-iteration, conditionals, parallel execution)
|
||||
- **WASM sandboxing** for custom code (no Python upload = secure)
|
||||
- **Marketplace** for sharing tools and complete flows
|
||||
- **Anti-paperclipper** design with user-controlled memory
|
||||
|
||||
---
|
||||
|
||||
## System Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ USERS │
|
||||
│ (Browser / API Clients) │
|
||||
└───────────────────────────────┬─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ VERCEL (Frontend) │
|
||||
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Next.js Application │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ Flow Canvas │ │ YAML Tab │ │ Monaco │ │ │
|
||||
│ │ │ (React Flow)│ │ (Preview) │ │ (WASM) │ │ │
|
||||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ Dashboard │ │ Marketplace │ │ Settings │ │ │
|
||||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
||||
│ └───────────────────────────────────────────────────────────────────┘ │
|
||||
└───────────────────────────────┬─────────────────────────────────────────┘
|
||||
│ REST / GraphQL
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ RENDER (Backend) │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Control Plane (FastAPI) │ │
|
||||
│ │ • User management (via Clerk webhooks) │ │
|
||||
│ │ • Flow CRUD (organism.yaml storage) │ │
|
||||
│ │ • Pump orchestration (start/stop/scale) │ │
|
||||
│ │ • Trigger routing (webhooks → pump injection) │ │
|
||||
│ │ • Marketplace catalog │ │
|
||||
│ │ • WASM module registry │ │
|
||||
│ │ • Billing integration (Stripe) │ │
|
||||
│ └───────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ │ Orchestrates │
|
||||
│ ▼ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Pump │ │ Pump │ │ Pump │ │
|
||||
│ │ Container │ │ Container │ │ Container │ │
|
||||
│ │ (Flow A) │ │ (Flow B) │ │ (Flow C) │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ StreamPump │ │ StreamPump │ │ StreamPump │ │
|
||||
│ │ + WASM RT │ │ + WASM RT │ │ + WASM RT │ │
|
||||
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
||||
│ │ │ │ │
|
||||
│ └─────────────────┼─────────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Redis (Shared State) │ │
|
||||
│ │ • Context buffers: tenant:{id}:flow:{id}:buffer:* │ │
|
||||
│ │ • Thread registry: tenant:{id}:flow:{id}:registry:* │ │
|
||||
│ │ • Project memory: tenant:{id}:flow:{id}:memory:* (opt-in) │ │
|
||||
│ └───────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ PostgreSQL (Persistent) │ │
|
||||
│ │ • Users, organizations │ │
|
||||
│ │ • Flows (organism.yaml stored as text) │ │
|
||||
│ │ • Marketplace listings │ │
|
||||
│ │ • WASM modules (metadata, S3 refs) │ │
|
||||
│ │ • Billing records │ │
|
||||
│ └───────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ EXTERNAL SERVICES │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Clerk │ │ Stripe │ │ LLM APIs │ │ S3 │ │
|
||||
│ │ (Auth) │ │ (Billing)│ │ (xAI,etc)│ │ (WASM) │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tier Model
|
||||
|
||||
| Tier | Price | Flows | Tools | Custom Code | Features |
|
||||
|------|-------|-------|-------|-------------|----------|
|
||||
| **Free** | $0 | 1 | Built-in only | ❌ | Community support |
|
||||
| **Paid** | $X/mo | Multiple | + Marketplace | ❌ | Email support |
|
||||
| **Pro** | $XX/mo | Unlimited | + Marketplace | ✅ WASM/WIT | Priority support |
|
||||
| **Enterprise** | Custom | Unlimited | + Private | ✅ WASM/WIT | SSO, roles, SLA |
|
||||
|
||||
### Limits (TBD)
|
||||
|
||||
| Resource | Free | Paid | Pro | Enterprise |
|
||||
|----------|------|------|-----|------------|
|
||||
| Flows | 1 | 10 | Unlimited | Unlimited |
|
||||
| Executions/month | 1,000 | 10,000 | 100,000 | Custom |
|
||||
| WASM modules | 0 | 0 | 10 | Unlimited |
|
||||
| Project memory | ❌ | 10MB | 100MB | Custom |
|
||||
| Team members | 1 | 1 | 1 | Unlimited |
|
||||
|
||||
---
|
||||
|
||||
## Component Architecture
|
||||
|
||||
### Frontend (Next.js on Vercel)
|
||||
|
||||
#### Tech Stack
|
||||
- **Framework:** Next.js 14+ (App Router)
|
||||
- **UI Generation:** Vercel v0
|
||||
- **Components:** shadcn/ui + Tailwind CSS
|
||||
- **Flow Canvas:** React Flow (Xyflow)
|
||||
- **Code Editor:** Monaco Editor
|
||||
- **State:** Zustand or Jotai
|
||||
- **API Client:** tRPC or React Query
|
||||
|
||||
#### Key Pages
|
||||
|
||||
| Route | Purpose |
|
||||
|-------|---------|
|
||||
| `/` | Landing page |
|
||||
| `/dashboard` | Flow list, usage stats |
|
||||
| `/flow/[id]` | Flow canvas editor |
|
||||
| `/flow/[id]/yaml` | YAML editor view |
|
||||
| `/flow/[id]/runs` | Execution history |
|
||||
| `/marketplace` | Browse tools/flows |
|
||||
| `/settings` | Account, billing, API keys |
|
||||
|
||||
#### Flow Canvas Features
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ [Save] [Run] [Stop] [YAML] [Canvas] [Split] │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ ┌───────────┐ │
|
||||
│ │ Palette │ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ │ │ Webhook │ ───▶ │ LLM │ ──┐ │
|
||||
│ │ [Built-in]│ │ Trigger │ │ Call │ │ │
|
||||
│ │ [Market] │ └─────────┘ └─────────┘ │ │
|
||||
│ │ [Custom] │ │ │
|
||||
│ │ │ ┌─────────┐ │ │
|
||||
│ │ 📦 Trigger│ │ Code │ ◀─┘ │
|
||||
│ │ 📦 LLM │ │ Block │ │
|
||||
│ │ 📦 HTTP │ └────┬────┘ │
|
||||
│ │ 📦 Code │ │ │
|
||||
│ │ 📦 Branch │ ▼ │
|
||||
│ │ ... │ ┌─────────┐ │
|
||||
│ └───────────┘ │ Output │ │
|
||||
│ └─────────┘ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ Minimap │ Zoom: 100% │ Nodes: 4 │ Status: Saved │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### Node Types
|
||||
|
||||
| Node | Visual | Maps To |
|
||||
|------|--------|---------|
|
||||
| Trigger | 🎯 Circle | Injection endpoint |
|
||||
| LLM Call | 🤖 Box | Agent listener |
|
||||
| HTTP Request | 🌐 Box | HTTP tool |
|
||||
| Code Block | 📝 Box | WASM handler |
|
||||
| Conditional | ◇ Diamond | Branch logic |
|
||||
| Output | 📤 Box | Terminal handler |
|
||||
| Loop | ↻ Arrow back | Self-iteration |
|
||||
|
||||
### Control Plane (FastAPI on Render)
|
||||
|
||||
#### Tech Stack
|
||||
- **Framework:** FastAPI
|
||||
- **ORM:** SQLAlchemy 2.0 + asyncpg
|
||||
- **Validation:** Pydantic v2
|
||||
- **Task Queue:** (Optional) Celery or arq
|
||||
- **Container Orchestration:** Render Native (or Docker API)
|
||||
|
||||
#### API Endpoints
|
||||
|
||||
```
|
||||
Authentication (via Clerk)
|
||||
───────────────────────────
|
||||
POST /webhooks/clerk # Clerk webhook for user sync
|
||||
|
||||
Flows
|
||||
───────────────────────────
|
||||
GET /api/flows # List user's flows
|
||||
POST /api/flows # Create flow
|
||||
GET /api/flows/{id} # Get flow details
|
||||
PUT /api/flows/{id} # Update flow (canvas → YAML)
|
||||
DELETE /api/flows/{id} # Delete flow
|
||||
POST /api/flows/{id}/start # Start pump container
|
||||
POST /api/flows/{id}/stop # Stop pump container
|
||||
GET /api/flows/{id}/status # Pump status
|
||||
GET /api/flows/{id}/logs # Stream logs
|
||||
|
||||
Triggers
|
||||
───────────────────────────
|
||||
POST /api/triggers/{flow_id}/webhook/{token} # Webhook ingress
|
||||
POST /api/triggers/{flow_id}/inject # Manual injection
|
||||
|
||||
Marketplace
|
||||
───────────────────────────
|
||||
GET /api/marketplace/tools # Browse tools
|
||||
GET /api/marketplace/flows # Browse flow templates
|
||||
POST /api/marketplace/publish # Publish to marketplace
|
||||
|
||||
WASM Modules (Pro+)
|
||||
───────────────────────────
|
||||
GET /api/modules # List user's modules
|
||||
POST /api/modules # Upload WASM module
|
||||
DELETE /api/modules/{id} # Delete module
|
||||
```
|
||||
|
||||
#### Database Schema (PostgreSQL)
|
||||
|
||||
```sql
|
||||
-- Users (synced from Clerk)
|
||||
CREATE TABLE users (
|
||||
id UUID PRIMARY KEY,
|
||||
clerk_id TEXT UNIQUE NOT NULL,
|
||||
email TEXT NOT NULL,
|
||||
tier TEXT DEFAULT 'free',
|
||||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- Flows
|
||||
CREATE TABLE flows (
|
||||
id UUID PRIMARY KEY,
|
||||
user_id UUID REFERENCES users(id),
|
||||
name TEXT NOT NULL,
|
||||
description TEXT,
|
||||
organism_yaml TEXT NOT NULL, -- The actual config
|
||||
canvas_state JSONB, -- React Flow state
|
||||
status TEXT DEFAULT 'stopped', -- stopped, starting, running, error
|
||||
container_id TEXT, -- Render container ID
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- WASM Modules
|
||||
CREATE TABLE wasm_modules (
|
||||
id UUID PRIMARY KEY,
|
||||
user_id UUID REFERENCES users(id),
|
||||
name TEXT NOT NULL,
|
||||
description TEXT,
|
||||
s3_key TEXT NOT NULL, -- S3 path to .wasm file
|
||||
wit_interface TEXT, -- WIT definition
|
||||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- Marketplace Listings
|
||||
CREATE TABLE marketplace_listings (
|
||||
id UUID PRIMARY KEY,
|
||||
author_id UUID REFERENCES users(id),
|
||||
type TEXT NOT NULL, -- 'tool' or 'flow'
|
||||
name TEXT NOT NULL,
|
||||
description TEXT,
|
||||
content JSONB NOT NULL, -- Tool def or flow template
|
||||
downloads INT DEFAULT 0,
|
||||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- Execution History
|
||||
CREATE TABLE executions (
|
||||
id UUID PRIMARY KEY,
|
||||
flow_id UUID REFERENCES flows(id),
|
||||
trigger_type TEXT, -- webhook, manual, schedule
|
||||
started_at TIMESTAMPTZ,
|
||||
completed_at TIMESTAMPTZ,
|
||||
status TEXT, -- success, error
|
||||
error_message TEXT
|
||||
);
|
||||
```
|
||||
|
||||
### Pump Containers (Render)
|
||||
|
||||
Each flow gets its own container running:
|
||||
- StreamPump (from xml-pipeline)
|
||||
- WASM runtime (wasmtime)
|
||||
- Redis connection (shared state)
|
||||
|
||||
#### Container Image
|
||||
|
||||
```dockerfile
|
||||
FROM python:3.11-slim
|
||||
|
||||
# Install xml-pipeline
|
||||
COPY requirements.txt .
|
||||
RUN pip install -r requirements.txt
|
||||
|
||||
# Install wasmtime
|
||||
RUN pip install wasmtime
|
||||
|
||||
# Copy entrypoint
|
||||
COPY entrypoint.py .
|
||||
|
||||
# Environment variables provided by orchestrator:
|
||||
# - FLOW_ID
|
||||
# - ORGANISM_YAML (base64 encoded)
|
||||
# - REDIS_URL
|
||||
# - TENANT_PREFIX
|
||||
|
||||
CMD ["python", "entrypoint.py"]
|
||||
```
|
||||
|
||||
#### Entrypoint
|
||||
|
||||
```python
|
||||
# entrypoint.py
|
||||
import os
|
||||
import base64
|
||||
import asyncio
|
||||
from xml_pipeline.message_bus.stream_pump import StreamPump
|
||||
from xml_pipeline.config.loader import load_config_from_string
|
||||
from xml_pipeline.memory.shared_backend import get_shared_backend, BackendConfig
|
||||
|
||||
async def main():
|
||||
# Load config from environment
|
||||
yaml_content = base64.b64decode(os.environ["ORGANISM_YAML"]).decode()
|
||||
config = load_config_from_string(yaml_content)
|
||||
|
||||
# Configure shared backend with tenant prefix
|
||||
backend_config = BackendConfig(
|
||||
backend_type="redis",
|
||||
redis_url=os.environ["REDIS_URL"],
|
||||
redis_prefix=os.environ["TENANT_PREFIX"],
|
||||
)
|
||||
backend = get_shared_backend(backend_config)
|
||||
|
||||
# Start pump
|
||||
pump = StreamPump(config, backend=backend)
|
||||
await pump.start()
|
||||
|
||||
# Keep running
|
||||
try:
|
||||
while True:
|
||||
await asyncio.sleep(1)
|
||||
except asyncio.CancelledError:
|
||||
await pump.shutdown()
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Trigger System
|
||||
|
||||
Triggers inject messages into running pumps.
|
||||
|
||||
### Trigger Types
|
||||
|
||||
| Trigger | Implementation |
|
||||
|---------|----------------|
|
||||
| **Webhook** | Control plane receives POST, forwards to pump via Redis pub/sub |
|
||||
| **Schedule** | Celery beat or Render Cron, injects at scheduled times |
|
||||
| **Manual** | "Run" button in UI, calls control plane API |
|
||||
| **Email** | (Future) IMAP polling service |
|
||||
|
||||
### Webhook Flow
|
||||
|
||||
```
|
||||
External Service
|
||||
│
|
||||
│ POST /api/triggers/{flow_id}/webhook/{token}
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Control Plane │
|
||||
│ │
|
||||
│ 1. Validate │
|
||||
│ 2. Find pump │
|
||||
│ 3. Publish │
|
||||
└────────┬────────┘
|
||||
│ Redis PUBLISH trigger:{flow_id}
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Pump Container │
|
||||
│ │
|
||||
│ 1. Subscribe │
|
||||
│ 2. Inject msg │
|
||||
│ 3. Process │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Model
|
||||
|
||||
### Multi-Tenancy Isolation
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Tenant A │
|
||||
│ ┌────────────┐ ┌────────────┐ │
|
||||
│ │ Flow 1 │ │ Flow 2 │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ Redis: │ │ Redis: │ │
|
||||
│ │ tenantA: │ │ tenantA: │ │
|
||||
│ │ flow1:* │ │ flow2:* │ │
|
||||
│ └────────────┘ └────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Tenant B │
|
||||
│ ┌────────────┐ │
|
||||
│ │ Flow 3 │ ← Cannot access tenantA:* keys │
|
||||
│ │ │ │
|
||||
│ │ Redis: │ │
|
||||
│ │ tenantB: │ │
|
||||
│ │ flow3:* │ │
|
||||
│ └────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### WASM Sandboxing
|
||||
|
||||
Custom code runs in WASM, which provides:
|
||||
- **Memory isolation** — Cannot access host memory
|
||||
- **No filesystem** — Only WIT-defined host functions
|
||||
- **No network** — Must use provided HTTP tool
|
||||
- **CPU limits** — Fuel-based execution limits
|
||||
- **Deterministic** — Same input → same output
|
||||
|
||||
### Memory Safety (Anti-Paperclipper)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Memory Tiers │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Thread Memory (automatic) │
|
||||
│ ├── Per-execution context buffer │
|
||||
│ ├── Pruned when thread completes │
|
||||
│ └── Swarm cannot prevent deletion │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Project Memory (opt-in, Pro+) │
|
||||
│ ├── User explicitly enables per flow │
|
||||
│ ├── Size limits enforced │
|
||||
│ ├── User can view/delete anytime │
|
||||
│ └── Cleared on flow deletion │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Cross-Flow Memory (FORBIDDEN) │
|
||||
│ ├── Flow A cannot read Flow B's memory │
|
||||
│ ├── Even same user, different flows = isolated │
|
||||
│ └── Prevents swarm coordination across boundaries │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow Examples
|
||||
|
||||
### User Creates Flow
|
||||
|
||||
```
|
||||
1. User drags nodes on canvas
|
||||
2. Frontend converts to organism.yaml
|
||||
3. PUT /api/flows/{id} with YAML
|
||||
4. Control plane validates YAML
|
||||
5. Saves to PostgreSQL
|
||||
6. Returns success
|
||||
```
|
||||
|
||||
### User Starts Flow
|
||||
|
||||
```
|
||||
1. User clicks "Start"
|
||||
2. POST /api/flows/{id}/start
|
||||
3. Control plane:
|
||||
a. Fetches YAML from DB
|
||||
b. Creates Render container
|
||||
c. Passes YAML + Redis config as env vars
|
||||
d. Updates flow.status = 'starting'
|
||||
4. Container starts, pump initializes
|
||||
5. Pump reports ready via Redis
|
||||
6. Control plane updates flow.status = 'running'
|
||||
7. Frontend shows green "Running" status
|
||||
```
|
||||
|
||||
### Webhook Triggers Flow
|
||||
|
||||
```
|
||||
1. External service POSTs to webhook URL
|
||||
2. Control plane receives at /api/triggers/{flow_id}/webhook/{token}
|
||||
3. Control plane validates token
|
||||
4. Control plane publishes to Redis: PUBLISH trigger:{flow_id} {payload}
|
||||
5. Pump container (subscribed) receives message
|
||||
6. Pump injects message into StreamPump
|
||||
7. Pipeline processes, handlers execute
|
||||
8. Results logged to execution history
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Canvas ↔ YAML Synchronization
|
||||
|
||||
### Canvas → YAML
|
||||
|
||||
```javascript
|
||||
// Frontend: Convert React Flow state to organism.yaml
|
||||
function canvasToYaml(nodes, edges) {
|
||||
const listeners = nodes
|
||||
.filter(n => n.type !== 'trigger')
|
||||
.map(node => ({
|
||||
name: node.data.name,
|
||||
handler: node.data.handler,
|
||||
payload_class: node.data.payloadClass,
|
||||
description: node.data.description,
|
||||
agent: node.data.isAgent || false,
|
||||
peers: edges
|
||||
.filter(e => e.source === node.id)
|
||||
.map(e => findNode(e.target).data.name),
|
||||
}));
|
||||
|
||||
return yaml.dump({
|
||||
organism: { name: flowName },
|
||||
listeners,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### YAML → Canvas
|
||||
|
||||
```javascript
|
||||
// Frontend: Convert organism.yaml to React Flow state
|
||||
function yamlToCanvas(yamlContent) {
|
||||
const config = yaml.load(yamlContent);
|
||||
|
||||
const nodes = config.listeners.map((listener, i) => ({
|
||||
id: listener.name,
|
||||
type: getNodeType(listener),
|
||||
position: calculatePosition(i),
|
||||
data: {
|
||||
name: listener.name,
|
||||
handler: listener.handler,
|
||||
payloadClass: listener.payload_class,
|
||||
description: listener.description,
|
||||
isAgent: listener.agent,
|
||||
},
|
||||
}));
|
||||
|
||||
const edges = config.listeners.flatMap(listener =>
|
||||
(listener.peers || []).map(peer => ({
|
||||
id: `${listener.name}-${peer}`,
|
||||
source: listener.name,
|
||||
target: peer,
|
||||
}))
|
||||
);
|
||||
|
||||
return { nodes, edges };
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Marketplace
|
||||
|
||||
### Publishing a Tool
|
||||
|
||||
```
|
||||
1. User creates WASM module (Pro+)
|
||||
2. User clicks "Publish to Marketplace"
|
||||
3. Frontend sends:
|
||||
- Module metadata
|
||||
- Description, icon, category
|
||||
- Pricing (free or paid)
|
||||
4. Control plane:
|
||||
- Validates module
|
||||
- Creates marketplace listing
|
||||
- Makes module available to others
|
||||
```
|
||||
|
||||
### Installing a Tool
|
||||
|
||||
```
|
||||
1. User browses marketplace
|
||||
2. User clicks "Install" on tool
|
||||
3. Control plane:
|
||||
- Adds tool to user's available tools
|
||||
- Copies WASM module reference
|
||||
4. Tool appears in user's palette under "Marketplace" tab
|
||||
```
|
||||
|
||||
### Publishing a Flow Template
|
||||
|
||||
```
|
||||
1. User creates working flow
|
||||
2. User clicks "Publish as Template"
|
||||
3. Frontend sends:
|
||||
- Flow YAML (sanitized)
|
||||
- Description, use case
|
||||
4. Control plane creates listing
|
||||
5. Other users can "Use Template" to clone flow
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
### Metrics (Prometheus/Grafana)
|
||||
|
||||
| Metric | Description |
|
||||
|--------|-------------|
|
||||
| `nextra_flows_total` | Total flows by status |
|
||||
| `nextra_executions_total` | Executions by flow, status |
|
||||
| `nextra_pump_memory_bytes` | Memory per pump container |
|
||||
| `nextra_pump_messages_total` | Messages processed |
|
||||
| `nextra_api_requests_total` | API requests by endpoint |
|
||||
|
||||
### Logging
|
||||
|
||||
- **Control Plane:** Structured JSON logs → CloudWatch/Datadog
|
||||
- **Pump Containers:** Stream to Redis → Viewable in UI
|
||||
- **Execution History:** Stored in PostgreSQL
|
||||
|
||||
### Alerting
|
||||
|
||||
| Alert | Condition |
|
||||
|-------|-----------|
|
||||
| Pump crash | Container exits unexpectedly |
|
||||
| High error rate | >5% executions failing |
|
||||
| Memory pressure | Pump using >80% memory |
|
||||
| Stuck flow | No messages processed in 5min |
|
||||
|
||||
---
|
||||
|
||||
## Scaling Considerations
|
||||
|
||||
### Render Service Types
|
||||
|
||||
| Component | Render Service | Scaling |
|
||||
|-----------|----------------|---------|
|
||||
| Control Plane | Web Service | Horizontal (multiple instances) |
|
||||
| Pump Containers | Private Services | Per-flow, scale-to-zero |
|
||||
| Redis | Managed Redis | Vertical |
|
||||
| PostgreSQL | Managed Postgres | Vertical |
|
||||
|
||||
### Scale-to-Zero (Cost Optimization)
|
||||
|
||||
```
|
||||
Free tier flows:
|
||||
- Auto-stop after 15 min idle
|
||||
- Webhook triggers wake container (~5s cold start)
|
||||
- User sees "Starting..." briefly
|
||||
|
||||
Paid tier flows:
|
||||
- Keep-alive option
|
||||
- Faster cold starts (warm pool)
|
||||
```
|
||||
|
||||
### Future: Multi-Region
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ US-East │ │ EU-West │ │ AP-Tokyo │
|
||||
│ │ │ │ │ │
|
||||
│ Control Plane│ ←───│ Control Plane│ ←───│ Control Plane│
|
||||
│ Pump Pool │ │ Pump Pool │ │ Pump Pool │
|
||||
│ Redis │ │ Redis │ │ Redis │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
│ │ │
|
||||
└───────────────────┼───────────────────┘
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ Global Postgres │
|
||||
│ (CockroachDB?) │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: MVP (4-6 weeks)
|
||||
|
||||
- [ ] Control Plane basic CRUD
|
||||
- [ ] Single pump container (manual start/stop)
|
||||
- [ ] Canvas with basic nodes (LLM, HTTP, Output)
|
||||
- [ ] YAML preview (read-only)
|
||||
- [ ] Clerk authentication
|
||||
- [ ] Free tier only
|
||||
|
||||
### Phase 2: Core Features (4-6 weeks)
|
||||
|
||||
- [ ] Automatic pump orchestration
|
||||
- [ ] Webhook triggers
|
||||
- [ ] Execution history
|
||||
- [ ] Canvas ↔ YAML sync
|
||||
- [ ] Paid tier + Stripe billing
|
||||
|
||||
### Phase 3: Pro Features (4-6 weeks)
|
||||
|
||||
- [ ] WASM module upload
|
||||
- [ ] Monaco editor integration
|
||||
- [ ] Project memory (opt-in)
|
||||
- [ ] Pro tier
|
||||
|
||||
### Phase 4: Marketplace (4-6 weeks)
|
||||
|
||||
- [ ] Tool publishing
|
||||
- [ ] Flow templates
|
||||
- [ ] Browse/search/install
|
||||
- [ ] Ratings/reviews
|
||||
|
||||
### Phase 5: Enterprise (TBD)
|
||||
|
||||
- [ ] Team/org management
|
||||
- [ ] Role-based access
|
||||
- [ ] SSO (SAML)
|
||||
- [ ] SLA dashboard
|
||||
- [ ] Private marketplace
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **Pricing specifics** — What are the actual price points?
|
||||
2. **Execution metering** — How to count/limit executions fairly?
|
||||
3. **WASM module review** — Manual review before marketplace publish?
|
||||
4. **Cold start optimization** — Warm container pool for paid users?
|
||||
5. **Mobile support** — Canvas on mobile, or just monitoring?
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Technology Decisions
|
||||
|
||||
| Decision | Choice | Rationale |
|
||||
|----------|--------|-----------|
|
||||
| Frontend Framework | Next.js | v0 generates it, Vercel hosts it |
|
||||
| Canvas Library | React Flow | Most popular, good docs, n8n uses it |
|
||||
| Control Plane | FastAPI | Matches xml-pipeline, async-native |
|
||||
| Database | PostgreSQL | Render managed, reliable |
|
||||
| Cache/Pubsub | Redis | Already needed for xml-pipeline shared backend |
|
||||
| Auth | Clerk | Free to 10K, great DX, handles OAuth |
|
||||
| Billing | Stripe | Standard, good APIs |
|
||||
| Frontend Hosting | Vercel | Built for Next.js |
|
||||
| Backend Hosting | Render | Simple, good DX, containers |
|
||||
| WASM Runtime | wasmtime | Best WIT support |
|
||||
|
||||
---
|
||||
|
||||
*Document generated: January 2026*
|
||||
*Next review: After Phase 1 completion*
|
||||
Loading…
Reference in a new issue