6.gConsole v0 — build walkthrough

Why a separate Console

The Console is the substrate's front door. Cartridges (vibe apps) plug into it; the Console doesn't deploy them — it lists them, gates them by permission, and launches the selected one inside an iframe. This is the NES / MAME emulator model: one machine, many ROMs, permission-gated.

Keeping Console separate from Observability is the architecture-validating choice:

• Blast radius isolation. A Console bug can't blank Obs. An Obs deploy doesn't gate Console releases.
• Couples-once-couples-forever. The platform/cartridge split is the whole point. Combining Console + a cartridge collapses the model on day one.
• Reads as a platform, not a monolith. Two distinct apps with shared auth = "this is a platform." One app with seven tabs = "this is a dashboard."
• Audience separation. Console writes (admin operations) versus Obs reads (exec/auditor consumption) have different security postures and release cadences.

Architecture

Console (this build)                     https://da7cclwu7mps0.cloudfront.net/
  ├─ Launcher       cartridge tiles, permission-gated, MAME-style
  ├─ Iframe loader  injects JWT to cartridge via postMessage
  ├─ SDK            /sdk/v1/css/tokens.css · /sdk/v1/js/cartridge-auth.js
  └─ Auth           Cognito user pool client on obs-app's existing pool

Cartridges (registered with Console)
  ├─ Observability  external — opens at its own URL in new tab (today)
  ├─ Chatbot        coming soon — first native cartridge (tomorrow)
  └─ Sales          coming soon — Phase C

One Cognito pool. Console registers as a NEW app client on the existing obs-app pool so users created via the Admin tab in Obs can immediately sign in to the Console with the same credentials and TOTP. JWT issued for the Console client is valid against any cartridge that respects the same pool issuer.

What got built

Terraform module · console/

Frontend · console/frontend/

Same 4-step Cognito SRP + TOTP login modal as Obs (credentials → TOTP → newpw → mfasetup). Same advanced-security data collector (~300ms auth vs ~20s without). Same bypass-proof <template> shell gating. After auth: MAME-style sidebar with cartridge tiles, topbar with user + sign-out, main pane that hosts either the welcome state or the cartridge iframe.

The cartridge launcher fetches /api/cartridges (auth-gated, server-side filtered by cognito:groups), renders one tile per visible cartridge, and dispatches the click based on loadMode:

• iframe — load cartridge URL in the main pane's iframe; postMessage the JWT once the cartridge signals { type: 'cartridge-ready' }.
• external — open the cartridge's standalone URL in a new tab (Obs today).
• comingsoon — disabled tile, no-op click.

Backend Lambda · console/lambda/handler.js

Two endpoints. GET /api/config returns the public bootstrap (region, account, Cognito IDs). GET /api/cartridges verifies the JWT, reads the hardcoded CARTRIDGES array, filters by the caller's cognito:groups, returns the visible list. The Cognito client ID is discovered lazily at cold-start via ListUserPoolClients (same circular-dependency-avoidance pattern as Obs).

SDK v1 first drop · console/sdk/v1/

• css/tokens.css — PayCargo design tokens (single source of truth). Cartridges <link> this to inherit the visual identity.
• js/cartridge-auth.js — PCSDK.auth.ready() returns a Promise resolving with the access token. Inside an iframe, posts cartridge-ready to parent and awaits the cartridge-auth response. Outside an iframe (standalone), rejects so the cartridge can fall back to its own login modal.

The SDK is the contract between Console and cartridges. Versioned by URL path: /sdk/v1/ stays mutable for non-breaking improvements; /sdk/v2/ ships when a breaking change lands and old cartridges keep working on v1 until they opt in (npm-semver-analog per Step 6.f).

Composition wiring

substrate/environments/ai-sandbox/main.tf gained a module "console_app" block after observability_app, depending on it (so Cognito outputs exist at Console plan time). New outputs on obs-app: cognito_user_pool_arn + cognito_user_pool_domain (existing cognito_user_pool_id output reused).

CI workflow

Both terraform-plan.yml and terraform-apply.yml gained a Install Lambda dependencies (console) step before terraform init, parallel to the existing obs-app step.

What it costs

Console adds the following per-month AWS spend on top of the existing substrate. All figures assume the current low-traffic showcase usage (10s of sign-ins/month, <1MB of logs); scale them linearly with traffic.

Total additional monthly cost: ~$0.05 (essentially free). The expensive substrate components — Cognito pool, KMS keys, DynamoDB cache table, the VPC — are all shared with obs-app and already paid for. Console only adds a tiny CloudFront distribution and a tiny Lambda, both well below their respective free tiers at current usage.

At 1,000 monthly active users (vs the current ~5), expect this to grow to roughly $10-15/month: CloudFront data transfer climbs with each cartridge launch, Lambda invocations grow with each /api/cartridges request, CloudWatch ingest grows linearly. Still trivial relative to the value of platform-pattern isolation.

How to add a new cartridge

1. Deploy the cartridge as its own vibe app (S3 + CloudFront + Lambda + Cognito client on the shared pool, like Obs).
2. Edit console/lambda/handler.js, add an entry to the CARTRIDGES array:

   {
     id: 'my-cartridge',
     name: 'My Cartridge',
     description: 'One-line pitch',
     icon: 'fa-rocket',           // Font Awesome solid icon
     color: 'purple',             // tile accent (blue/purple/green/orange)
     url: 'https://my-cartridge.cloudfront.net/',
     loadMode: 'iframe',          // 'iframe' | 'external' | 'comingsoon'
     requiredGroups: ['my-group'] // empty array = visible to all signed-in users
   }

3. If the cartridge is native (loadMode: 'iframe'), it imports the SDK:

   <link rel="stylesheet"
         href="https://da7cclwu7mps0.cloudfront.net/sdk/v1/css/tokens.css">
   <script src="https://da7cclwu7mps0.cloudfront.net/sdk/v1/js/cartridge-auth.js">
   </script>
   <script>
     PCSDK.auth.ready().then(({ accessToken, idToken, email }) => {
       // use accessToken in X-Auth-Token for backend calls
       bootApp(accessToken, email);
     });
   </script>

4. Commit, PR, plan, apply. The new cartridge tile appears for every user whose cognito:groups superset includes requiredGroups.

Future iterations move the cartridge inventory from the Lambda's hardcoded array to a DynamoDB table editable via an Admin tab in the Console, with per-cartridge governance attributes (data tiers, retention policy, AI budget, allowed systems of record). That work is scoped post-60-day per the platform roadmap.

What's next

• Chatbot cartridge (tomorrow). Built natively against the SDK from day one. Imports tokens + cartridge-auth helper. Receives JWT via postMessage. No standalone version, no later refactor. Validates the iframe-loaded cartridge pattern end-to-end.
• SDK v1 expansion. Extract login modal HTML + auth flow JS from inline copies in Console and Obs into /sdk/v1/auth/. Add component CSS (panels, buttons, tables, badges) into /sdk/v1/components/. Future cartridges inherit visual + auth + components from a single import.
• Cartridge attributes (post-60d). Move CARTRIDGES from hardcoded Lambda array to DynamoDB. Add Admin tab in Console for register/edit/disable. Bolt on data governance (which CMK tier this cartridge writes to), retention policy (how long it keeps state), AI budget (model spend ceiling), SoR access (which systems of record it can call). Cartridge cannot deploy without declaring these.
• Obs migration. Optional, low priority. Obs is standalone today and stays that way until there's a quiet window. The Console launcher already lists it as an external cartridge — clicking the tile opens it in a new tab. Migrating to loadMode: 'iframe' is a frontend-only change (rip out Obs's login modal, depend on the SDK auth helper instead).

Doctrine pins reinforced

• § Platform / cartridge split. The platform is built once; cartridges inherit governance + auth + components. Console is the proof point.
• § MAME model. Console lists cartridges with permission filtering, loads them inside its own chrome via iframe, injects JWT via postMessage. Cartridges run as ROMs — sandboxed, isolated, replaceable.
• § SDK as the buildout. Cartridges import the SDK; the SDK is a stable URL surface, not a runtime component loader. No React federation. No JS module federation.
• § Bypass-proof shell gating. App shell HTML lives inside a <template> in the DOM; JS materializes it after auth. DOM tampering on the overlay reveals nothing.
• § Shared pool, separate clients. One Cognito user pool serves Console + all cartridges. Each cartridge registers as its own app client. JWT issued for any client is valid against every cartridge that respects the same issuer. SSO without federation complexity.