Architecture

The EnterpriseAI platform uses a layered architecture where every vertical application connects to a shared set of backend services through a secure gateway. The browser never communicates with backend services directly -- all requests flow through a BFF (Backend-for-Frontend) proxy in the Next.js application, which injects authentication tokens server-side.

Platform Services

The platform consists of five backend services, each with a distinct responsibility:

Service	Purpose	Tech Stack
PublicAPI	Gateway that routes, validates, and proxies all platform calls	FastAPI
Configurator	Metadata registry for tenants, workflows, and object type schemas	PayloadCMS + MongoDB/Cosmos DB
ResourceAPI	Data CRUD for typed JSONB resources with versioning and history	FastAPI + PostgreSQL
AICore	AI services including RAG chat, document classification, and indexing	FastAPI
Authz	Authorization engine using OPA Rego policies for tenant-scoped RBAC	OPA

System Architecture Diagram

Request Flow

Every API call from the browser follows the same path through the platform. Here is what happens when a user creates a new resource:

Step-by-Step Breakdown

1. Browser sends a request to a Next.js API route (e.g., /api/eai/v3/resources/my-tenant/Application)
2. BFF proxy (src/app/api/eai/[[...rest]]/route.ts) intercepts the request, reads the user's Auth.js session, and extracts the access token. If no user session exists, it falls back to a client credentials token.
3. BFF proxy forwards the request to PublicAPI at the configured BASE_URL_PUBLIC_API, injecting the Authorization: Bearer {token} header
4. PublicAPI validates the JWT against Entra CIAM signing keys, then sends the request to Authz for a policy check
5. Authz evaluates OPA Rego policies to determine if the user has permission for this action in this tenant
6. PublicAPI routes the request to the appropriate downstream service (ResourceAPI for data operations, AICore for chat/documents, Configurator for metadata)
7. The response flows back through the same chain to the browser

Tokens Never Reach the Browser

This is a critical security property of the architecture. The BFF proxy injects authentication tokens server-side, so access tokens are never exposed to client-side JavaScript. The browser only sees an encrypted session cookie managed by Auth.js.

The Orchestrate Endpoint

The /v3/orchestrate endpoint is a generic proxy within PublicAPI that can route requests to any backend service. It is used when you need to call Configurator or other services directly:

caution

When using target_backend: "payload", the orchestrator automatically prepends /api to your endpoint. Do not include /api in your endpoint string. Use /object-types, not /api/object-types.

Two Proxy Paths

The Next.js application has two separate proxy routes for different types of requests:

Proxy Route	File	Purpose
/api/eai/[[...rest]]	src/app/api/eai/[[...rest]]/route.ts	Standard JSON proxy for all REST calls
/api/eai/stream/[[...rest]]	src/app/api/eai/stream/[[...rest]]/route.ts	SSE stream proxy for chat with explicit streaming headers

The stream proxy sets Content-Type: text/event-stream, Cache-Control: no-cache, and Connection: keep-alive headers, then forwards the ReadableStream directly from PublicAPI to the browser. This separation ensures that SSE streaming is not disrupted by content encoding or response buffering applied by the standard proxy.