Architecture Overview

Internal documentation

This section documents how Illumera is built and operated. It is visible only to signed-in users holding the platform_admin role, and is excluded from the public search index.

Illumera is a federated talent-marketplace SaaS platform that connects contracting companies, professional-services firms, and independent professionals through a structured, AI-enhanced matching engine. It is multi-tenant: each company operates inside an isolated tenant, and optional partnership agreements let talent visibility cross tenant boundaries.

Runtime topology

The browser loads the React SPA, which talks to the Express API over /api/*. The API is the only component with database access; every other service is stateless or supporting.

Browser
  └─► ftm-web (React 19 + Vite, base /ftm-web)
        └─► api-server (Express 5, /api/*)
              ├── PostgreSQL (Drizzle ORM)
              ├── Resend (transactional email — queue-based outbox)
              ├── Anthropic Claude (AI scoring — Sonnet 4.5 default)
              ├── Stripe (billing & Connect)
              ├── Tigris / S3 (object storage — resumes, avatars, reports)
              └── Align API (project + time-entry sync — outbox + webhooks)

Supporting services:
  illumera-www   — public marketing site
  illumera-docs  — this documentation site
  landing-portal — developer portal
  pdf-worker     — HTML-to-PDF rendering

The web app never imports the database package directly — all data access flows through the API. See Services & Packages for the full inventory (this docs site included), generated from the workspace itself.

The three personas

• Talent (Persons) maintain a profile, list skills and certifications, complete a culture assessment, and apply to or accept engagements.
• Companies create projects, define staffing slots, search the federated marketplace, run the engagement lifecycle, and use Capability Intelligence.
• Platform Administrators manage tenants, users and roles, feature flags, the audit trail, the skill/certification catalogue, and system-wide configuration.

Request lifecycle

1. Clerk authenticates the browser session; the API validates the bearer token on every /api/* request.
2. Middleware loads the DB user and derives the tenant server-side — the client-supplied x-tenant-id header is never trusted as a tenant source.
3. Role guards (requireRole([...])) authorize the route against the user's roles array.
4. Handlers read and write through Drizzle; responses are shaped by the OpenAPI contract.

Platform admins acquire tenant context only through an explicit impersonation session, not by asserting a tenant header. See Data Model for the isolation model.

Environments & domains

APP_ENV selects the environment (production, development, or local). Each node has a production and a development fully-qualified domain; the API asserts that its APP_DOMAIN belongs to the domain set for its APP_ENV at startup and exits on mismatch, so a dev image can never boot against production DNS.

Node	Production	Development
App (ftm-web)	app.illumera.us	devapp.illumera.us
API	api.illumera.us	apid.illumera.us
Marketing (www)	www.illumera.us	wwwd.illumera.us
Docs (this site)	docs.illumera.us	docd.illumera.us

Where to read next

• Services & Packages — the pnpm workspace inventory, generated from source.
• Data Model — entity groups, key enumerations, and tenant isolation.
• Match Scoring — the six-axis Spider engine and CVF culture fit.
• Configuration & Environments — the environment-variable reference, generated from .env.example.