How CORTEX is built and served.

One repo, one Vercel project, no root build. Static pages, committed app builds and serverless functions all ship from the same git push. The live site serves what is committed, not what is in source.

Edge Static sections Committed app builds Serverless API Ignite sandbox Shared assets External services GatedNeeds a cortex-session cookie

From browser to backend, top to bottom.

Every request enters through the Vercel edge. The edge either serves a committed file, runs a function under /api, or stops the request at the session gate.

Two paths explain most of the system.

A gated request shows how the edge and API cooperate. A release shows why source changes alone never reach the site.

Opening a gated app

  1. middleware.js finds no valid cortex-session cookie and sends a 302 to /login.html?next=<path>.
  2. sparkhub-auth.js stores a PKCE verifier and state, then redirects to SparkHub. Prod enters Kainos SSO first.
  3. SparkHub returns a code to sparkhub-callback.html. The helper checks state and posts the code and verifier to /api/sparkhub-login.
  4. api/sparkhub-login exchanges the code at /oauth/token and confirms identity at /api/partner-app/me.
  5. It signs an 8-hour expiry with CORTEX_SESSION_SECRET and sets the cookie. The browser keeps SparkHub tokens for Juno.
  6. The browser returns to next. The edge verifies the signature and expiry, then serves the committed bundle.

Shipping a change

  1. Edit source in the app folder, for example build/stash/src/.
  2. Run that app's own build: npm, or pnpm for PPS Catalog.
  3. Commit the regenerated app/ or out/ folder with the source.
  4. Push. Vercel git integration deploys the repo root as static files and api/ as functions.

No root build

Each app builds in its own folder. There is no root CI, lint or test workflow.

Fails closed

A missing CORTEX_SESSION_SECRET locks every gated prefix rather than opening it.

Static means public

Ungated files and client bundles are readable by anyone. Secrets belong in functions only.

Two credentials

SparkHub issues the access JWT for KB search. CORTEX issues its own HMAC cookie for pages. Neither stands in for the other.

Chat is open

api/chat needs no session. An in-process limiter allows a burst of 12, then 0.2 requests per second.

Page checks are cosmetic

Outside the three gated prefixes, the chrome's /api/verify check hides content in the browser. It does not protect file downloads.

Nexus has no backend

Customers ship in the bundle as a KB snapshot; research lives in localStorage. Cosmos DB appears only in separate Ignite runtimes.

Snapshots, not live reads

Nexus and Stash pull SparkHub KB data at build time. Refreshing them means a rebuild and a commit.

Two Ignite catalogues

The homepage reads ignite-data.js; the Ignite landing reads cards.json. Edit both or they drift further.