Platform Architecture

This is the engineering view of how a running Nexa deployment is wired: which process talks to which, over what, and where state lives. It complements the conceptual platform layers (Raw → Curated → Consumption) with the actual service topology. Read it before touching any cross-service contract.

Everything runs as containers on Kubernetes (EKS or AKS), fronted by Envoy Gateway. One browser SPA talks to one backend gateway, which fans out to a set of FastAPI services and an LLM mapping engine; a separate Git-driven runtime executes generated automations on the data platform.

Request path at a glance

Browser
  │  HTTPS (Envoy Gateway, *.nexa-drai.com)
  ▼
nexa-web (React/Vite SPA, :3000, path /)
  │  /api/*   (browser never calls a FastAPI service directly)
  ▼
nexa-backend (Express/TypeScript gateway, :4000, path /api)
  ├─ NEXA_DATABRICKS_API_URL ─▶ nexa-databricks-api  (FastAPI, path /platform, :8000)
  ├─ SNOWFLAKE_API_URL       ─▶ nexa-snowflake-api   (FastAPI)
  ├─ AGENT_API_HOST          ─▶ nexa-agents-api      (FastAPI, path /agentapi, :8000)
  └─ ACTG_AI_URL             ─▶ actg-ai              (FastAPI mapping/LLM engine, path /llm, :9000)

Git-driven runtime (asynchronous, not a synchronous call):
  nexa-agents-api ── writes artifacts to Git ─▶ nexa-workflow-automations ── CI deploys ─▶ Databricks jobs
                                                    │ writes results to Delta
                                                    ▼
  nexa-agents-api workers ── project Delta rows ─▶ Postgres

The rule that shapes the whole system: the frontend never calls a FastAPI service directly. All traffic funnels through nexa-backend, which authenticates the user, mints service tokens, and proxies to the right downstream API. This keeps auth, logging, and the Databricks-vs-Snowflake choice in one place.

The components

nexa-web — the UI

A React 18 + Vite single-page app (package aa-website, JavaScript/JSX). It renders every product surface: connectors, data integration/canvas (@xyflow/react), schema and domain masters, projections, agents, automations, dashboards, and cost/usage. It calls only /api/... (base URL from VITE_API_URL); the Vite dev server proxies /api to the backend. User login is Azure AD via MSAL. It holds no database — its only direct cloud call is S3 presigned uploads.

nexa-backend — the gateway

A Node/TypeScript Express 4 service (entry src/server.ts). It is the single API gateway and owns all web-domain state. It mounts roughly 50 route groups under /api/* and does two jobs:

1. Owns web data — users, roles, connectors, domain/schema/source masters, ETL/dataflow definitions, projections, canvas state, change control, notifications, settings, Slack, and agent/automation metadata — in Postgres via Sequelize (schema web).
2. Proxies compute — Databricks/Snowflake/agent/LLM operations to the FastAPI services. Each proxy controller mints a short-lived token (POST <base>/api/v1/auth/token with NEXA_CLIENT_ID/NEXA_CLIENT_SECRET) and forwards the request.

Databricks and Snowflake are exposed as parallel route families: /api/connectors, /api/pipelines, /api/jobs, /api/projections (Databricks) versus /api/snowflake/connectors, /api/snowflake/pipelines, etc. (Snowflake).

nexa-databricks-api / nexa-snowflake-api — the platform APIs

FastAPI services that are the control/data plane for the customer’s data platform. They manage catalog objects, connectors, pipelines, jobs/tasks, warehouses, deployments, lineage, secrets, tags, and code generation. nexa-databricks-api (Poetry, databricks-sdk, served at /platform) targets a Databricks workspace and Unity Catalog/Delta; nexa-snowflake-api (uv, snowflake-connector-python) is its Snowflake twin. Both keep metadata in Postgres (schema platform / sf_platform) and are called only by nexa-backend. See Snowflake vs Databricks.

nexa-agents-api — the agent/automation control plane

A FastAPI service that manages the lifecycle of agents and agentic automations: it validates and materializes agent/automation versions into Git, promotes and retires them across branches and environments, and exposes live deployment status. It writes artifacts to the nexa-databricks-agents and nexa-workflow-automations repos, and background workers project Delta runtime rows back into Postgres (schema agents). Served at /agentapi. Its Snowflake twin is nexa-snowflake-agents-api.

actg-ai — the mapping/LLM engine

A FastAPI + worker service (port 9000, path /llm) that does the AI-heavy mapping work: Raw→Curated→TDM (target data model) mapping generation, conflict detection and resolution, tagger/mapper stages, projections, and SQL editing. nexa-backend proxies to it via ACTG_AI_URL; it calls back into the backend through a webhook (/api/schema-master/raw-to-tdm-mapping-webhook) when async jobs finish. It uses Databricks Vector Search and model-serving endpoints, and stores state in Postgres schema llm.

The two planes: synchronous vs Git-driven

Nexa has two distinct execution models, and conflating them is the most common source of confusion.

Plane	How it runs	Examples
Synchronous request plane	HTTP request → backend → FastAPI → response	Browsing catalog, running a statement, generating a mapping
Git-driven runtime plane	API writes artifacts to Git → CI deploys → data platform executes → results land in Delta/Snowflake → projected back to Postgres	Deploying an automation, running a scheduled workflow

Caution

The runtime repos (nexa-workflow-automations, nexa-snowflake-automations) do not call the control-plane API at runtime. Git is the source of truth: the control plane writes artifacts, CI deploys the bundle/tasks, execution writes to Delta/Snowflake, and agents-api workers project outcomes back to Postgres. Treat the control plane and runtime plane as decoupled.

State

All services share one Postgres (AWS RDS, DB nexa-db), partitioned by schema so ownership is clear:

Schema	Owner	Contents
web	nexa-backend	users, connectors, masters, ETL/canvas, settings
platform / sf_platform	platform APIs	pipeline/job/deployment metadata
agents	agents APIs	agent & automation lifecycle state
llm	actg-ai	mapping jobs, conflict state

The actual analytical data lives in the data platform — Unity Catalog / Delta (Databricks) or Snowflake — never in Postgres. Some deployments also use a data-platform-managed Postgres (Databricks Lakebase, or Snowflake-managed Postgres) for specific features.

Infrastructure and delivery

Every service is a container built by GitHub Actions and pushed to ECR (AWS) or ACR (Azure) with branch-per-env tags, then rolled out by ArgoCD from nexa-deployments. See CI/CD, GitOps & Deployments, and AWS vs Azure. For exact repo ownership, see the cross-repo map.