Skip to main content

EAI App Template

The EAI App Template is the canonical public scaffold used by eai init. It is a Next.js app template for tenant-scoped applications on the EAI platform.

Quick Start​

eai init my-app
cd my-app
npm install
cp .env.example .env.local
npm run dev

Then connect it to a tenant:

eai login
eai tenant list --format json
eai tenant select <tenant-slug>
eai whoami
eai types validate
eai types seed --tenant-key template --tenant-id <tenant-id> --format json
eai types diff --tenant-key template --tenant-id <tenant-id>
eai resources schema --tenant-id <tenant-id> --format json

App Structure​

PathPurpose
src/eai.config/default.tsDefault tenant config, store slices, API paths, storage keys, and layout slots.
src/eai.config/index.tsTenant key to config registry.
src/eai.config/object-types.tsObject Type definitions for ResourceAPI-backed data.
src/eai.blocks.tsxComponent registry and app-local block extension point.
src/hooks/useResources.tsResourceAPI-backed business data.
src/hooks/useDocuments.tsDocument upload, classification, and RAG indexing.
src/hooks/useChat.tsStreaming and non-streaming chat workflows.
src/app/providers.tsxAuth/session providers and EAI config runtime.

Platform Boundary​

  • Browser code calls the app BFF at /api/eai/....
  • Browser streaming calls use /api/eai/stream/....
  • Server helpers attach auth, tenant, and correlation headers.
  • The browser never receives raw database, blob, search, PublicAPI, or model provider credentials.
  • Prefer PublicAPI V4 routes; older route families are compatibility glue.

Data Model​

Object Types are the contract for tenant business data. Use postgresql for most canonical structured resources unless another backend is clearly required.

BackendUse For
postgresqlStructured business records, workflow status, joins, history, list/query/aggregate behavior.
documentdbResource types that genuinely need document-model persistence.
blobLarge files or file-like resources behind API-managed metadata.
searchDerived full-text, vector, or hybrid projections.

Search is not the system of record for mutable runtime data.

UI Composition​

The template uses config-driven UI:

  1. Define store slices and layout slots in config.
  2. Register components in src/eai.blocks.tsx.
  3. Reference components from config by registered name.
  4. Use storeBindings for data-driven props.
  5. Use JSON-safe showWhen conditions for visibility.
  6. Keep callbacks, router actions, auth actions, analytics hooks, and React nodes in code-level overrides.

See Config-Driven UI for the full pattern.

Service Hooks​

NeedApp PatternCLI Verification
Tenant business recordsuseResources('<ObjectType>')eai resources list/get/create/update/delete/query
Documents and RAGuseDocuments()eai docs upload, eai docs classify, eai docs index
AI chatuseChat(workflowId, stage)eai chat send, eai chat stream
Advanced routeserver helper or BFF routeeai publicapi <method> /v4/...