Reference Architecture

This page is the reference a platform or security reviewer uses to approve a Nexa deployment: every container that runs, how they talk, which ports are open, what state is stored where, and exactly what enters or leaves your environment. It describes the reference deployment shipped in DataReadyAI’s IaC and Kubernetes manifests; your sizing and hostnames will differ.

Topology at a glance

All Nexa services run as stateless Kubernetes Deployments on your cluster. Ingress terminates at an Envoy Gateway behind a cloud load balancer; TLS is issued by cert-manager. Persistent state lives outside the cluster in managed Postgres and your warehouse.

                          Internet (your users, API clients)
                                     │  HTTPS 443
                                     ▼
        ┌───────────────── Cloud load balancer (NLB / Azure LB) ─────────────────┐
        │                        Envoy Gateway  (:80 → 301 → :443)               │
        └───────────────────────────────┬───────────────────────────────────────┘
                                         │ HTTPRoute (Gateway API)
        ┌────────────────────────────────┼────────────────────────────────────────┐
        │  Kubernetes cluster (EKS / AKS)                                          │
        │                                                                          │
        │   nexa-web  :3000 ─────► nexa-backend :4000 ──► nexa-orchestration :8003 │
        │                                │                        │ (KEDA worker)  │
        │                                ├──► nexa-databricks-api :8000 (+worker)  │
        │                                │        or nexa-snowflake-api :8000      │
        │                                ├──► nexa-agents-api :8000 (+worker)      │
        │                                └──► actg-ai :9000, slackbot :8000, …     │
        │                                                                          │
        │   cert-manager · Secrets Store CSI · ArgoCD (GitOps)                     │
        └───────────┬───────────────────────────────────┬──────────────────────────┘
                    │ 5432 (TLS)                         │ 443 (warehouse API)
                    ▼                                     ▼
         Managed PostgreSQL 15               Snowflake  /  Databricks workspace
         (Nexa metadata)                     (Raw / Curated / Consumption data)

Component inventory

Every workload is a stateless Deployment (no StatefulSet); durable state lives in Postgres and the warehouse. Ports below are container ports exposed via a ClusterIP Service.

Component	Type	Port	State	Purpose
nexa-web	Deployment (stateless)	3000	none	Web UI
nexa-backend	Deployment (stateless)	4000	Postgres	Core API (TypeScript); orchestrates the other services
nexa-databricks-api	Deployment + worker	8000	Postgres	Warehouse API for Databricks (FastAPI)
nexa-snowflake-api	Deployment	8000	Postgres	Warehouse API for Snowflake (FastAPI)
nexa-agents-api	Deployment + worker	8000	Postgres	Agents & agentic automations (FastAPI)
nexa-orchestration-service	Deployment + worker	8003	Postgres	Background job/queue orchestration; worker scaled by KEDA
actg-ai	Deployment + worker	9000	Postgres	AI/analytics service
nexa-slackbot-service	Deployment	8000	none	Slack integration
nexa-teams-ingress-bridge	Deployment	8000	none	Microsoft Teams ingress bridge
nexa-stt-service	Deployment	8010	emptyDir cache	Speech-to-text (large; optional)

Supporting platform components (not Nexa application code):

Component	Namespace	Role
Envoy Gateway	envoy-gateway-system	Gateway API ingress; terminates TLS, HTTP→HTTPS redirect
cert-manager	cert-manager	Issues/renews TLS certs via Let’s Encrypt DNS-01
Secrets Store CSI driver	kube-system / provider ns	Mounts secrets from your cloud secret store into pods
ArgoCD	argocd	GitOps controller; syncs manifests from Git
KEDA	cluster-wide	Scales the orchestration worker to zero when idle

Note

Services run with a hardened pod security context (non-root, dropped Linux capabilities, no privilege escalation) in the reference manifests. The warehouse API you deploy depends on your warehouse choice — deploy nexa-databricks-api or nexa-snowflake-api, not both. Health endpoints vary by service (for example nexa-backend uses /health-check, the FastAPI services use /health or /api/v1/health, orchestration and STT expose /readyz).

Network topology

AWS

• VPC with two Availability Zones. Reference CIDR 10.0.0.0/16 (dev); public subnets (10.0.101.0/24, 10.0.102.0/24) and private subnets (10.0.1.0/24, 10.0.2.0/24).
• Ingress: an AWS Network Load Balancer (NLB) fronts the Envoy Gateway; a Route 53 A/ALIAS record (<env>.nexa-drai.com) points at it.
• Egress: a single NAT gateway in a public subnet; all private subnets route 0.0.0.0/0 through it. No VPC interface endpoints in the reference build — AWS API traffic exits via NAT/IGW.
• EKS API server: both private and public endpoints enabled in the reference build; restrict the public endpoint per your policy.
• Security groups: the RDS security group allows inbound 5432 from the VPC CIDR (plus any explicit allow-list). Node/cluster SGs are AWS-managed.

Azure

• App VNet with reference address space 10.1.0.0/16 (dev). Subnets: AKS (10.1.0.0/22), private-endpoints (10.1.12.0/24), App Gateway (10.1.13.0/24), and a delegated PostgreSQL subnet (10.1.14.0/24).
• Databricks (if used): a separate, peered VNet (10.4.0.0/16 dev) with delegated private/public subnets for secure cluster connectivity (no public IP on workers).
• Ingress: an Azure Load Balancer fronts the Envoy Gateway; an Azure DNS record in the delegated az.nexa-drai.com subzone points at its public IP.
• Egress: a Standard NAT gateway with a static public IP associated to the AKS subnet.
• AKS networking: Azure CNI Overlay with Calico network policy (pod CIDR 192.168.0.0/16, service CIDR 172.16.0.0/16).
• AKS API server: public in the reference build; enable a private cluster per your policy.

Ports

Port	Direction	Between	Notes
443	Inbound	Internet → load balancer/Envoy	User & API traffic (TLS terminated at Envoy)
80	Inbound	Internet → Envoy	Redirected 301 to 443
3000/4000/8000/8003/8010/9000	Internal	Envoy → Services, Service → Service	Cluster-internal HTTP only (ClusterIP)
5432	Outbound (in-cloud)	Pods → managed Postgres	TLS to your metadata DB
443	Outbound (in-cloud)	Warehouse API → Snowflake/Databricks	Warehouse control/SQL calls
443	Outbound	cert-manager → Let’s Encrypt / DNS API	ACME DNS-01 challenge
443	Outbound	Agents → model endpoints	LLM/model calls you configure

Data flows and what leaves the environment

1. User → UI → APIs. Browser hits nexa-web, which calls nexa-backend, which fans out to the warehouse API, nexa-agents-api, and nexa-orchestration-service. All in-cluster over HTTP.
2. Metadata persistence. Nexa’s own state (projects, glossary, pipeline definitions, job records, cost data) is written to managed Postgres 15 over 5432 — stays in your cloud.
3. Warehouse execution. The warehouse API translates Nexa actions into SQL/jobs/pipelines against your Snowflake or Databricks over 443. Your business data never transits into Nexa’s own storage — it stays in the warehouse.
4. Background work. nexa-orchestration-service and per-service workers poll Postgres queues and run generated pipelines; KEDA scales the orchestration worker on queue depth (idle → zero).
5. TLS issuance. cert-manager solves an ACME DNS-01 challenge against your DNS provider (Route 53 / Azure DNS) to obtain Let’s Encrypt certificates.

Crossing the boundary out of your environment:

Flow	Destination	Contains
ACME DNS-01 validation	Let’s Encrypt (acme-v02.api.letsencrypt.org) + your DNS API	Domain names only
Model/LLM calls (agent features)	Model endpoints you configure	Prompts/context, not bulk datasets
Image/base-layer pulls (build/deploy)	Your registry (internal) + public base registries	Container layers

There is no default telemetry or license call-home to DataReadyAI. Your data and metadata never leave your account under normal operation.

Storage and state

State	Where it lives	Cloud service
Nexa metadata (projects, glossary, jobs, cost)	Managed Postgres 15, database appdb	RDS (AWS) / PostgreSQL Flexible Server (Azure)
Business data (Raw/Curated/Consumption)	Your warehouse	Snowflake / Databricks + object storage
Secrets	Cloud secret store, mounted via CSI	Secrets Manager (AWS) / Key Vault (Azure)
TLS certificates	Kubernetes Secrets, managed by cert-manager	in-cluster
STT model cache	Pod emptyDir (ephemeral)	node disk

External dependencies

• Container registry (ECR / ACR) for the Nexa images.
• Managed Postgres 15 for Nexa metadata.
• Snowflake or Databricks workspace for data execution.
• GitHub for GitOps (ArgoCD sync) and for pipeline code Nexa generates and commits.
• Let’s Encrypt (or your own CA) for TLS.
• Model endpoints for agent features.

For the exact permissions, quotas, and sizing behind these, see Prerequisites. For controls and hardening, see Security & networking.