Core System Architecture & API Reference Manual (Level 2)

Milestone: v0.1.0-ga-epic17 · Audience: IT administrators, architects, DevOps, security auditors

1. Architectural blueprint

The platform uses a decoupled dual-plane topology — user interaction on Ironframe, autonomous advisory workforce on Ironboard — with shared PostgreSQL persistence.

+---------------------------------------------+       +---------------------------------------------+
|        IRONFRAME APPLICATION PLANE          |       |         IRONBOARD ENGINE PLANE              |
| ------------------------------------------- |       | ------------------------------------------- |
| - Next.js 15 App Router (port 3000)         |       | - Express HTTP server (port 8082)         |
| - Supabase Auth + multi-tenant RLS          |======>| - Gemini SSE boardroom query gateway        |
| - Prisma ORM / PostgreSQL core              |<======| - Core telemetry bridge → :3000 shared ctx  |
| - APP_DOCS reader (/docs → app_documents)   |       | - LangGraph CLI orchestration (offline)     |
+---------------------------------------------+       +---------------------------------------------+

IronBoard production runtime is the Express server in Ironboard/src/index.ts. LangGraph.js orchestration exists for offline/CLI deliberation workflows; it is not the live :8082 request path. There is no PostgresSaver checkpoint layer in the IronBoard production server.

Guardrail ingress rules

Irongate DMZ shielding — All inbound telemetry and mutations route through the Irongate sanitization layer. Direct Prisma access from unverified routes is prohibited. Verified by tests/architecture/gatewayShield.test.ts.

Zero floating-point financials — Currency uses BigInt whole-integer cents in PostgreSQL. Serialization middleware (lib/utils/serialization.ts, lib/prisma.ts) prevents JSON boundary crashes.

Documentation sync (not “write-back”)

IronBoard Trainer/Writer personas consume GET /api/board/shared-context (one-way telemetry + brief). Published chapters sync into Ironframe via bearer-gated POST /api/documentation/execute on both hosts — upserting app_documents and mirroring to docs/ (app/api/documentation/execute/route.ts, Ironboard/src/index.ts). This is documentation execute sync, not a general IronBoard→Ironframe core mutation path.

Baseline tenant financial anchors

2. Nineteen-agent workforce reference matrix

Canonical indices from app/config/agents.ts (CORE_WORKFORCE_AGENTS):

Kimbot is a simulated adversary for shadow-plane drills — not production Agent 17 (Ironbloom).

Boardroom personas (17) consume live telemetry via the shared-context bridge; they are read-only advisory — no direct database writes.

3. API reference & ingress schemas

Sustainability telemetry ingress

Representative request body (structured fields — at least one physical quantity required):

{
  assetId?: string;
  tenantId?: string; // UUID; resolved from session when omitted
  zone?: string;
  kwh?: number;       // or units_kwh / unitsKwh / physicalUnits.kwh
  liters?: number;    // or L / physicalUnits.liters
  km?: number;        // or physicalUnits.km
  fuelCategory?: "diesel" | "gasoline" | "natural_gas" | "generic";
}

Representative success response (app/api/sustainability/ironbloom/route.ts):

{
  "ok": true,
  "accepted": true,
  "tenantId": "5c420f5a-8f1f-4bbf-b42d-7f8dd4bb6a01",
  "carbonTrace": {
    "physicalUnit": "kWh",
    "physicalQuantity": 1500,
    "carbonGramsCo2e": "667500",
    "serializedTrace": "{…}"
  }
}

Parsing pipeline: validateIronbloomIngress() → computeIronbloomCarbonTrace() in lib/sustainability/ironbloom.ts.

Shared context cross-port bus

Implementation: app/lib/board/sharedBoardContext.ts · bridge: Ironboard/src/services/coreTelemetryBridge.ts.

Documentation execute sync

Additional pilot endpoints

Commercial SKUs, Phase 2/3 roadmap: Epic 17 Billing Architecture · Pricing & Packaging. | GET /api/board/feed | RSS syndication (cron secret) | | GET /api/internal/cron/industry-scout | Regulatory RSS → CRM catalyst bridge |

4. GTM market data authenticity (Ironboard)

The flywheel no longer uses a blind row count. verifyAndOptimizeMarketData() in Ironboard/src/services/marketProspectAuthenticity.ts:

1. Assesses market_prospects rows per region
2. Flags expansion templates ({Region} Ledger / {Region} Vault, -ledger.io, -vault.finance)
3. Purges synthetic rows and forces discoverRegionalProspects() web grounding

Board system prompt includes BOARD_GTM_MARKET_AUTHENTICITY_MANDATE — synthetic scaffolding must never be cited as live market research.

Sources

• docs/TAS.md
• Epic 17 Billing Architecture
• config/route-manifest.v0.1.0-ga-epic17.json
• app/config/agents.ts
• app/lib/security/ingressGateway.ts
• Ironboard/src/staticContext.ts