Platform Services

The EnterpriseAI platform is composed of five backend services. Each service has a single, well-defined responsibility and communicates via REST APIs. PublicAPI acts as the gateway -- all external traffic enters through PublicAPI, which routes requests to the appropriate downstream service after authentication and authorization checks.

PublicAPI (Gateway)

Purpose: Central gateway that routes, validates, and proxies all platform calls.

Tech Stack: FastAPI (Python)

Base Path: /v3

PublicAPI is the only service exposed to external traffic. It receives requests from the BFF proxy, validates JWT tokens against Entra CIAM signing keys, checks authorization policies via Authz, and then forwards the request to the correct downstream service.

Key Capabilities

• JWT validation -- Verifies access tokens against Entra CIAM signing keys
• Request routing -- Maps URL paths to downstream services (/v3/resources/* to ResourceAPI, /v3/chat/* to AICore, etc.)
• Authorization enforcement -- Calls Authz before forwarding any request
• Orchestrate proxy -- The /v3/orchestrate endpoint can route to any backend by specifying target_backend
• SSE forwarding -- Streams Server-Sent Events from AICore chat endpoints back through to the client

API Surface

Path Pattern	Routes To
/v3/resources/*	ResourceAPI
/v3/chat/*	AICore
/v3/documents/*	AICore
/v3/orchestrate	Configurator, ResourceAPI, or Mid-Layer (based on target_backend)
/v3/auth/*	Internal auth endpoints
/v3/users/*	User provisioning

---

Configurator (Metadata Registry)

Purpose: Stores and manages tenant configurations, workflow definitions, and object type schemas.

Tech Stack: PayloadCMS + MongoDB/Cosmos DB

Configurator is the source of truth for all platform metadata. When you define object types in your vertical's src/eai.config/object-types.ts and seed them, they are stored in Configurator. At runtime, ResourceAPI reads schemas from Configurator to validate incoming data.

Key Capabilities

• Tenant registry -- Stores tenant configurations including branding, features, and navigation
• Object type schemas -- Stores the data model definitions that ResourceAPI uses for validation
• Workflow definitions -- Manages AI workflow configurations (chat stages, prompts, RAG settings)
• PayloadCMS admin -- Provides a web-based admin panel for managing metadata

Accessing Configurator

Configurator is not accessed directly. All calls go through PublicAPI's orchestrate endpoint:

// Example: Fetch object types from Configurator
const response = await client.orchestrate({
  target_backend: 'payload',
  endpoint: '/object-types',  // Do NOT include /api prefix
  method: 'GET',
});

---

ResourceAPI (Data CRUD)

Purpose: Stores and retrieves domain data as typed JSONB resources with versioning, actions, and link types.

Tech Stack: FastAPI (Python) + PostgreSQL

ResourceAPI is the primary data store for all vertical applications. Each resource belongs to a tenant, has a type (defined by an Object Type in Configurator), and stores its data as JSONB in PostgreSQL. ResourceAPI enforces schema validation, maintains version history, and supports relationship links between resources.

Key Capabilities

• CRUD operations -- Create, read, update, delete resources with automatic schema validation
• Optimistic locking -- Updates require a version field to prevent concurrent write conflicts
• Version history -- Every mutation is recorded; full history is available via the history endpoint
• Actions -- Custom operations defined in Object Types (e.g., "submit", "approve") that modify resource state
• Link types -- Typed relationships between resources (one-to-one, one-to-many, many-to-many)
• Query engine -- Cross-type queries with filtering, joining, and pagination
• Tenant scoping -- All data is scoped by tenant; no cross-tenant data access is possible

API Endpoints

Operation	Method	Path
Create	POST	/v3/resources/{tenant}/{type}
Get	GET	/v3/resources/{tenant}/{type}/{id}
List	GET	/v3/resources/{tenant}/{type}
Update	PUT	/v3/resources/{tenant}/{type}/{id}
Delete	DELETE	/v3/resources/{tenant}/{type}/{id}
Execute Action	POST	/v3/resources/{tenant}/{type}/{id}/actions/{action}
Get Links	GET	/v3/resources/{tenant}/{type}/{id}/links/{linkType}
Query	POST	/v3/resources/{tenant}/query
Get History	GET	/v3/resources/{tenant}/{type}/{id}/history
Get Schema	GET	/v3/resources/schema/{tenant}

---

AICore (AI Services)

Purpose: Provides AI-powered capabilities including RAG chat, document classification, and document indexing.

Tech Stack: FastAPI (Python)

AICore powers the conversational AI and document processing features of the platform. Chat uses Server-Sent Events (SSE) for real-time streaming responses. Document processing includes classification (identifying document types) and RAG indexing (making documents searchable by AI).

Key Capabilities

• RAG chat -- Retrieval-Augmented Generation chat with SSE streaming responses
• Document classification -- Automatic identification of document types from uploaded files
• Document indexing -- Indexes documents for retrieval during chat sessions
• Workflow stages -- Chat interactions are organized by workflow and stage, allowing different prompts and RAG contexts per stage
• Conversation management -- Maintains conversation history for multi-turn interactions

API Endpoints

Operation	Method	Path
Stream Chat	POST	/v3/chat/stream/{tenant}/{workflow}/{stage}
Send Chat	POST	/v3/chat/{tenant}/{workflow}/{stage}
Upload Document	POST	/v3/documents/upload
Classify Documents	POST	/v3/documents/classify
Classify by URL	POST	/v3/documents/classify-by-url
RAG Index	POST	/v3/documents/rag-index
Get Checklist	POST	/v3/documents/checklist

---

Authz (Authorization)

Purpose: Evaluates tenant-scoped RBAC policies to determine whether a user can perform a given action.

Tech Stack: OPA (Open Policy Agent) with Rego policies

Authz is called by PublicAPI before every request is forwarded to a downstream service. It evaluates Rego policies that define what each role can do within each tenant. Policies are scoped by tenant, so the same user can have different permissions in different tenants.

Key Capabilities

• Tenant-scoped RBAC -- Policies are evaluated per-tenant, allowing fine-grained access control
• Role-based permissions -- Three standard roles: tenant-user, tenant-staff, tenant-admin
• Collection-level access -- Read/write/admin permissions can be set per object type collection
• Action authorization -- Object Type actions can specify a requiredRole for execution
• OPA Rego policies -- Policies are written in Rego, a declarative language purpose-built for authorization

Role Hierarchy

Role	Description	Typical Permissions
tenant-user	End user of the application	Read own resources, create new resources, execute basic actions
tenant-staff	Internal staff member	Read/write all resources, execute staff-level actions
tenant-admin	Tenant administrator	Full access including configuration and user management