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 diff --tenant-key template --tenant-id <tenant-id>
eai types seed --tenant-key template --tenant-id <tenant-id> --format json
eai resources schema --tenant-id <tenant-id> --format json
App Structure
| Path | Purpose |
|---|---|
src/eai.config/default.ts | Default tenant config, store slices, API paths, storage keys, and layout slots. |
src/eai.config/index.ts | Tenant key to config registry. |
src/eai.config/object-types.ts | Object Type definitions for ResourceAPI-backed data. |
src/eai.blocks.tsx | Component registry and app-local block extension point. |
src/hooks/useResources.ts | ResourceAPI-backed business data. |
src/hooks/useDocuments.ts | Document upload, classification, and RAG indexing. |
src/hooks/useChat.ts | Streaming and non-streaming chat workflows. |
src/app/providers.tsx | Auth/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.
Each definition keeps a PascalCase source/model name and an explicit exact
lowercase kebab-case persisted/transport slug. Do not convert the complete
definition to one case. Emitted linkTypes[].targetObjectType, runtime
target_type, resource command arguments, paths, and governed v4 fields use
exact stored slugs. Same-manifest model names may be authoring shorthand only
when tooling resolves them through the declared slug before publication.
Historical stored slugs remain authoritative.
| Backend | Use For |
|---|---|
postgresql | Structured business records, workflow status, joins, history, list/query/aggregate behavior. |
documentdb | Resource types that genuinely need document-model persistence. |
blob | Large files or file-like resources behind API-managed metadata. |
search | Derived 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:
- Define store slices and layout slots in config.
- Register components in
src/eai.blocks.tsx. - Reference components from config by registered name.
- Use
storeBindingsfor data-driven props. - Use JSON-safe
showWhenconditions for visibility. - 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
| Need | App Pattern | CLI Verification |
|---|---|---|
| Tenant business records | useResources('<ObjectType>') | eai resources list/get/create/update/delete/query |
| Documents and RAG | useDocuments() | eai docs upload, eai docs classify, eai docs index |
| Resource file property | useResources().uploadFile | eai resources file upload/get/delete |
| AI chat | useChat(workflowId, stage) | eai chat send, eai chat stream |
| Advanced route | server helper or BFF route | eai publicapi <method> /v4/... |