Architecture

All external traffic enters on port 443 (HTTPS) handled by nginx, which terminates SSL and proxies every request to the bridge-gateway on port 8080. The gateway is the single orchestration point — it authenticates requests, enforces mission check, applies rate limiting, and routes to downstream services.

Gateway: Single Entry Point

The bridge-gateway is a Node.js Express server at :8080. nginx proxies all requests to 127.0.0.1:8080 (IPv4 — never localhost as it resolves to ::1 on this VPS). The gateway handles:

• JWT verification middleware on all /api/* routes
• Mission check middleware (withMissionCheck()) blocking access if entity has no active mission
• Rate limiting via Redis token bucket
• Static file serving from /var/www/bridgeai/public/ for the Vite frontend shell
• Proxying to brain, unified, and auth services

Brain: :8000

The super-brain is a Python FastAPI service. It handles all AI operations: the 10-agent swarm, AIC Phases 1–3, RAG (retrieval-augmented generation), autonomous trading, anomaly detection, and intelligence reporting. It exposes a WebSocket at /ws/<channel> for live event streaming.

Supabase Database

Supabase (hosted PostgreSQL + Auth) stores all persistent state. Key tables: users, wallets, leads, missions, decisions, treasury_splits, apps, brands. The auth service uses the Supabase admin client with SUPABASE_SERVICE_KEY for server-side operations.

Authentication

Bridge AI OS supports two authentication flows: direct email/password (issues Bridge JWT immediately) and OAuth via Supabase PKCE (Google, GitHub).

Auth Flows

Flow 1: Email/Password

1. POST /auth/login with { email, password }
2. Auth service validates credentials against Supabase
3. Returns signed Bridge JWT — store in localStorage.bridge_token

Flow 2: OAuth PKCE (Google / GitHub)

1. Login page calls supabase.auth.signInWithOAuth({ provider })
2. Browser redirects to Supabase OAuth → provider → back to /auth-callback
3. auth-callback.html parses the URL hash/fragment, extracts the Supabase session
4. POSTs access_token to /auth/token-exchange
5. Receives Bridge JWT — stored in localStorage and as a 7-day cookie

JWT Payload

{
  "sub": "uuid-from-supabase",
  "id": "bridge-internal-user-id",
  "email": "user@example.com",
  "role": "user",          // "user" | "admin" | "superadmin"
  "plan": "pro",           // "free" | "pro" | "enterprise"
  "tier": "pro",           // mirrors plan
  "wallet_id": "wallet-uuid",
  "iat": 1745000000,
  "exp": 1745604800     // 7-day expiry
}

Calling APIs

const callAPI = async (path, options = {}) => {
  const token = localStorage.getItem('bridge_token');
  const response = await fetch(path, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
      ...(options.headers || {})
    }
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
};

// Example: fetch current user
const me = await callAPI('/auth/me');

Zero-Trust Root Token

For system-to-system communication without a user session, use the root token endpoint:

curl -X POST https://go.ai-os.co.za/api/auth/root-token \
  -H "X-Zero-Trust-Secret: $ZERO_TRUST_SECRET" \
  -H "Content-Type: application/json"

AEOS Economy

AEOS — Autonomous Economic Operating System — governs all revenue flows. Every transaction processed through the platform automatically applies a 4-way split enforced at the treasury layer.

Revenue Split

• 80% — User (creator): Goes directly to the entity that generated the revenue
• 10% — Ops bank: Platform operational reserve — infrastructure, scaling, emergencies
• 5% — Platform fee (Ryan): Founding team allocation
• 5% — Token burn (BRDG): Deflationary mechanism on Linea zkEVM

Auto-Split Endpoint

POST /api/treasury/auto-split
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount_zar": 1000,
  "source": "marketplace_sale"
}

Response:

{
  "success": true,
  "split": {
    "user": 800,
    "ops": 100,
    "platform": 50,
    "burn": 50
  },
  "currency": "ZAR",
  "transaction_id": "txn_abc123"
}

Wallet Balance

GET /api/economy/me
Authorization: Bearer <token>

Response includes balance_zar, balance_brdg, wallet_id, and total_earned.

Dual Currency

ZAR (Fiat): South African Rand processed via PayFast, Paystack, or bank transfer. Stored in Supabase wallets table.

BRDG (Token): ERC-20 token on Linea zkEVM. 5% of every transaction is burned on-chain. Used for marketplace transactions, staking, and governance. Bridge between fiat and on-chain via the treasury service.

Mission Statement Engine

The MSE is a governance layer that generates AI-powered mission statements for every entity on the platform. No entity can access protected APIs without an active mission.

What is a Mission?

A mission is an AI-generated governance document tied to an entity (user, company, agent, or product). It contains:

• mission text: A natural-language statement of purpose
• rules[]: Behavioral constraints the entity must operate within
• terms[]: Legal terms and conditions specific to the entity type
• status: active or expired
• expiry: 1 year from generation — must be renewed

withMissionCheck() Middleware

Applied to all protected API routes. Blocks access and returns HTTP 403 if:

• The entity has no mission record in Supabase
• The mission status is expired
• The entity_id is null or undefined (null guard added 2026-04-25)

Generate Mission

POST /api/mission/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "entity_type": "company",   // "user" | "company" | "agent" | "product"
  "entity_id": "uuid-here",
  "context": {
    "name": "Acme Corp",
    "industry": "fintech",
    "goals": "Automate B2B sales pipeline"
  }
}

Response:

{
  "mission_id": "msn_xyz789",
  "entity_type": "company",
  "mission": "To autonomously generate and close B2B sales opportunities using AI-driven intelligence, operating with integrity and measurable impact.",
  "rules": [
    "Operate transparently with all stakeholders",
    "Never engage in deceptive sales practices",
    "Respect data privacy at all times"
  ],
  "terms": [
    "Subject to Bridge AI OS platform terms of service",
    "Revenue split applies as per AEOS protocol"
  ],
  "status": "active",
  "expires_at": "2027-04-25T00:00:00Z"
}

AIC — Autonomous Intelligence Core

AIC is the decision-making backbone of Bridge AI OS. It progresses through three phases of autonomy, each unlocking more powerful capabilities.

Phase 1: Foundation

• Classification: Classifies input signals into entity types and intent categories
• Routing: Routes classified signals to appropriate swarm agents
• Agents: Dispatches and monitors swarm agent execution
• Decisions: Records all agent decisions in Supabase for audit trail
• Feedback: Collects outcome feedback to train scoring models

Phase 2: Intelligence

• Opportunity scoring: Formula — (EDV × CP × SVM) / TTC where EDV = Expected Deal Value, CP = Conversion Probability, SVM = Strategic Value Multiplier, TTC = Time to Close
• Simulation: Monte Carlo simulation of opportunity outcomes (1000 runs)
• Queue management: Priority queue routing based on score thresholds
• State tracking: Full pipeline state with per-agent metrics
• Reinvestment: Auto-routes high-scoring opportunities to closer agent
• Process v2: Enhanced orchestration with scoring integration

Phase 3: Autonomy

• Deal closure loop: Autonomous closer agent runs end-to-end deal closure without human intervention
• Autonomy Index: 0–100 score measuring system self-sufficiency — 100 means fully autonomous
• Anomaly detection: Real-time time-series anomaly detection on revenue and activity streams
• Intelligence reporting: Automated briefings on anomalies, opportunities, and strategic recommendations
• System manifest: Full AIC configuration and capability declaration

AIC Endpoints Reference

API Reference

All endpoints are served through the bridge-gateway at https://go.ai-os.co.za. Requests to /api/* require a valid Bridge JWT unless marked as public.

Authentication

Economy & Treasury

Missions

Leads & CRM

Platform Utilities

Agent SDK

The Agent SDK allows you to register custom agents with the AIC execution server and route tasks through the swarm pipeline.

Agent Types

The platform includes 10 built-in specialist agent types:

Processing a Task

// POST /api/aic/process
const response = await fetch('/api/aic/process', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_type: 'growth',
    payload: {
      task: 'generate_lead_list',
      industry: 'fintech',
      count: 20
    },
    priority: 'high'   // "low" | "medium" | "high"
  })
});
const result = await response.json();
// result.job_id — use to poll agent status
// result.decision_id — Supabase decisions table row

Agent Scoring

// Score an opportunity before routing
const score = await fetch('/api/aic/score', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    edv: 50000,    // Expected Deal Value (ZAR)
    cp: 0.65,     // Conversion Probability 0-1
    svm: 1.2,    // Strategic Value Multiplier
    ttc: 14       // Time to Close (days)
  })
}).then(r => r.json());
// score.aic_score — numeric priority score

Frontend Integration

The Bridge AI OS frontend is a collection of self-contained HTML files served from /var/www/bridgeai/public/ (the nginx vhost default root). There is no build step — files are deployed directly.

auth-callback.html — PKCE Flow

After Supabase OAuth, the browser lands on /auth-callback. The page:

1. Detects #access_token= in the URL fragment from Supabase
2. Calls supabase.auth.getSession() to confirm the session
3. POSTs the access_token to /auth/token-exchange
4. Receives Bridge JWT and stores it
5. Redirects based on user state (see routing logic below)

localStorage Keys

Auth Cookie

Alongside localStorage, the Bridge JWT is set as an HTTP cookie:

Set-Cookie: bridge_token=<jwt>; Max-Age=604800; Path=/; SameSite=Lax; Secure; HttpOnly

Post-Login Routing

After successful auth, the client redirects based on user state in this priority order:

1. role === 'superadmin' → /dashboard
2. user.wizard === 1 (setup not complete) → /wizard
3. user.plan === null (no plan selected) → /checkout
4. Otherwise → /profile

function routeAfterLogin(user) {
  if (user.role === 'superadmin') return redirect('/dashboard');
  if (user.wizard === 1)         return redirect('/wizard');
  if (!user.plan)               return redirect('/checkout');
  redirect('/profile');
}

Deployment & Ops

All services run under PM2 at /var/www/bridgeai/ on the VPS at root@102.208.228.44.

PM2 Commands

# List all services
pm2 list

# Restart specific service
pm2 restart bridge-gateway
pm2 restart unified-server
pm2 restart super-brain
pm2 restart auth-service

# View logs
pm2 logs bridge-gateway --lines 100
pm2 logs super-brain --lines 50

# Save process list (persist across reboots)
pm2 save

# Restart all services
pm2 restart all

# Monitor live dashboard
pm2 monit

nginx Configuration

nginx is split into two vhost files managed by scripts/update-nginx.sh:

• bridgeai — HTTP :80 (redirects to HTTPS)
• bridgeai-ssl — HTTPS :443 with SSL termination

# Key proxy block — always use 127.0.0.1, never localhost
location / {
  proxy_pass         http://127.0.0.1:8080;
  proxy_http_version 1.1;
  proxy_set_header   Upgrade $http_upgrade;
  proxy_set_header   Connection 'upgrade';
  proxy_set_header   Host $host;
  proxy_cache_bypass $http_upgrade;
}

Environment Variables

Health Check

# Gateway health
curl https://go.ai-os.co.za/health
# Expected: {"status":"OK","uptime":12345}

# Brain health (requires auth)
curl -H "Authorization: Bearer $TOKEN" \
  https://go.ai-os.co.za/api/brain/status

Log Files

• /var/www/bridgeai/logs/gateway-out.log
• /var/www/bridgeai/logs/gateway-err.log
• /var/www/bridgeai/logs/unified-out.log
• /var/www/bridgeai/logs/unified-err.log
• /var/www/bridgeai/logs/auth-out.log
• /var/www/bridgeai/logs/auth-err.log
• /var/www/bridgeai/logs/brain-out.log

Changelog

All notable changes to Bridge AI OS, most recent first.