Bridge AI OS Docs

Bridge AI OS is a sovereign, agent-driven operating system for real-world economic automation. It runs AI agents, mints BRDG tokens, distributes UBI, orchestrates sales pipelines, and exposes every capability as an executable skill.

Architecture

The system is a 5-tier stack, each layer building on the one below:

Data Flow

Payment (PayFast ITN)
  → /api/payfast/itn
  → treasury.ingest(amount_zar)
  → 5-bucket split (ops/growth/ubi/reserve/founder)
  → BRDG mint on Linea via TreasuryVault.mintFor()
  → reconciler cron validates on-chain parity
  → /api/live/report reflects updated economy state

Microservices

Frontend Pages

All pages include the unified bridge-nav.js navigation bar — auto-injects top nav + mobile drawer, role-gated links, live health dot.

Navigation

All pages load /bridge-nav.js which self-injects a role-aware top bar and mobile drawer. No markup required — just the script tag.

<!-- Add to any page -->
<script src="/bridge-nav.js"></script>

<!-- Optional: set user role before the script -->
<script>window.__BRIDGE_USER = {role:'user', name:'Alice'};</script>

Role visibility: null = public · user = authenticated · admin · superadmin. The nav reads localStorage.bridge_user automatically.

API — System

API — Twins & Agents

API — SVG Skills Engine

Execute Response Schema

{
  "ok": true,
  "skill": "bridge.economy",
  "action": "economy_cycle_triggered",
  "latency_ms": 14,
  "result": {
    "cycle": 3842,
    "brdg_minted": 0.0312,
    "bucket": "ops",
    "agents_updated": 8
  },
  "ts": 1712345678901
}

Available Skill IDs

API — Economy & Treasury

API — CRM & Pipeline

API — Streaming

API — Marketplace, Projects & Users

BRDG Token

BRDG is the native utility token of Bridge AI OS, deployed on Linea mainnet.

Mint Flow

1. User pays ZAR via PayFast checkout
2. PayFast sends ITN (Instant Transaction Notification) to /api/payfast/itn
3. API validates payment signature
4. treasury.ingest(amount_zar) → splits to 5 buckets
5. TreasuryVault.mintFor(userAddress, brdgAmount) on Linea
6. DB ledger updated, reconciler cron verifies parity

Revenue Buckets

Every ZAR payment is split across 5 buckets at the time of ingestion:

UBI System

Universal Basic Income is distributed from the ubi bucket to all registered agents on a per-epoch basis.

• Epoch: 24h (triggered by cron at midnight UTC)
• Distribution: proportional to agent health score × activity weight
• Minimum distribution: 0.001 BRDG / agent / epoch
• Pool visible at /api/bi/status → ubi_pool
• Agents must have status = active and at least 1 execution in the epoch

Skills Engine — Overview

The SVG Skills Engine renders every agent capability as an interactive SVG diagram. Skills are executable units that can be inspected, visualized, and run from the dashboard or via API.

• Click a skill node → inspect detail panel (inputs, outputs, description)
• Double-click → execute skill via POST /api/execute
• Human-readable mode → plain-English execution output alongside raw JSON
• Exec badges → pulse animation on nodes when execution count increases
• Pan/zoom → drag canvas, mouse wheel zoom

The engine is accessible at /svg-engine.html and embedded in the AoE dashboard's VIS tab.

Skills — Full List

Skills — API Usage

List Skills

GET /api/svg/skills
→ { ok: true, skills: [{id, name, tags, version, description}] }

Execute a Skill

POST /api/execute
Content-Type: application/json
{ "skill": "bridge.swarm" }

→ {
  "ok": true,
  "skill": "bridge.swarm",
  "action": "swarm_healthcheck_run",
  "latency_ms": 11,
  "result": { "agents": 8, "healthy": 7, "score": 0.94, "tasks_dispatched": 3 },
  "ts": 1712345678901
}

Render Skill SVG

GET /api/svg/bridge.economy
→ Content-Type: image/svg+xml
   (standalone SVG diagram)

Interactive Graph Data

GET /api/svg/graph.json
→ {
  ok: true,
  nodes: [{id, name, description, tags, inputs, outputs, color, position:{x,y}}],
  edges: [{from, to, shared:[...tags]}],
  canvas: {width:900, height:560}
}

Skills — A5E Contract Format

Every skill beyond the core bridge.* set is defined by an A5E skill contract — a JSON file in shared/skills/ that fully describes the skill's runtime, graph bindings, events, data contracts, workflows, UI modes, and security roles.

Workflow Step Types

Workflow API

POST /api/skills/:skill_id/workflow/:workflow_id
Content-Type: application/json
{}

→ {
  "ok": true,
  "workflow": "leadgen",
  "label": "Lead Generation",
  "steps_completed": 3,
  "outputs_emitted": ["lead.captured", "marketing.campaign.launched"],
  "results": { "select_audience": {...}, "launch_campaigns": {...}, "sync_leads": {...} },
  "latency_ms": 145,
  "ts": 1712345678901
}

Skill — biz.marketing

Pipeline Stages

API Endpoints

Events

Roles

Environment Variables

Local Ports

Deployment

Vercel (Production)

Deployed at go.ai-os.co.za via Vercel.

# Build command (vercel.json)
"buildCommand": "node build-static.js"

# Output directory
"outputDirectory": "public"

# API function
api/index.js → Vercel Serverless Function

Build Steps

node build-static.js
  1. Copy root-level .html/.css/.js/.svg → public/
  2. Copy Xpublic/*.html → public/ (XPUB_SKIP: docs.html, svg-engine.html)
  3. Inject SEO meta tags into all HTML (inject-meta.js)
  4. Generate public/ban-ultra.svg (animated activity bars)
  5. Generate public/ban-live-console.svg (animated log lines)
  6. Pre-render 9 skill SVGs → public/output/*.svg
  7. Generate public/output/index.html (skill listing)

Vercel Rewrites

Key rewrites in vercel.json:

/api/svg/:path* → /api (handled by api/index.js)
/teach/:path*   → /api (svg/teach/* aliased)
/docs           → /docs.html
/gateway        → /gateway/
/join           → /join.html

Cron Jobs (12 active)

• Economy reconciler — every 5 minutes
• UBI distribution — daily at midnight UTC
• NeuroLink campaign processor — every 2 minutes
• HITL timeout checker — every 10 minutes
• Swarm health score updater — every minute
• Lead nurture sequence — every 15 minutes
• Subscription enforcement — hourly
• Treasury parity audit — every 30 minutes