Concepts and architecture

This page is written so someone who has never seen Cere Insight 2.0 can form a mental model: what each part means, how they connect, and which screen supports which job. If you add screenshots later, suggested placements are marked with Screenshot callouts.

How to read this documentation

• Internalize concepts first, then follow the Learning path.
• For in-app tasks, use the UI guide and the relevant Usage pages.
• For developer integration, use the API section.

Screenshot

A high-level product diagram or “home screen” image can go here.

System architecture (high level)

Cere Insight 2.0 is usually made of three layers:

1. Web app (frontend)
   Next.js (App Router) and React. After sign-in, most pages use a left sidebar, top bar, and content region.

2. API server (backend)
   NestJS REST API. Authentication, organization scoping, subscription limits, and business logic live here. Data access goes through Prisma to the database.

3. Live messaging and queues
   Customer conversations run on the product’s built-in live messaging layer. Bot replies and test mode often use Redis with BullMQ so heavy work does not block HTTP requests.

A simple data flow:

flowchart LR
  subgraph client [Browser]
    UI[Next.js UI]
  end
  subgraph api [Backend]
    REST[NestJS REST]
    Q[Redis / BullMQ]
  end
  subgraph channels [Channels and AI]
    LC[Live messaging]
    LLM[LLM providers]
  end
  UI -->|JWT + X-Organization-Id| REST
  REST --> Q
  REST --> LLM
  REST <-->|REST / webhook| LC

Super admin caveat

SUPERADMIN can manage organizations and messaging environment records, but bot app CRUD expects a normal organization context — the backend rejects super admins without org for those routes. Day-to-day bot configuration is done as an org member.

Glossary

Term	Definition
Organization	Tenant boundary for projects, knowledge bases, and billing. Users can belong to more than one.
Membership role	Inside an org: ORG_ADMIN or MEMBER. Many guards depend on this (who may create projects, etc.).
Account role	On the user record: USER or SUPERADMIN. Super admins see extra nav items (e.g. messaging environment instances).
Project (Bot App)	Definition of one chat experience: system prompt, LLM settings, board, agents, tools, integrations.
Agent	An LLM worker for a role; can have its own system prompt and model settings. A router agent can branch flow.
Tool	A capability the model can call (e.g. knowledge search or HTTP API). Some tools are defined at project level and linked to agents.
API integration	Connection to an external REST service (base URL, auth, default request config). Tools call through integrations.
Knowledge base	Document store with embedding search; supports RAG.
Board	Visual flow editor (React Flow style): nodes and edges for “who calls whom”.
Inbox	Platform messaging line; web, email, WhatsApp channels attach here and map to bot and live agents.
Analytics agent	Dashboards, data sources, and natural-language queries — separate from chat projects.
Orchestration	Org-scoped workflows with triggers (may require subscription workflows feature).
Reports	Metrics from live messaging and live agent operations; contact-level reporting lives under /reports/users.

Request and session model (web → API)

Almost every protected browser call needs:

• Authorization: Bearer <accessToken> — JWT identity.
• X-Organization-Id: <uuid> — which tenant you act in. With multiple memberships, the organization switcher updates this value.

Next.js middleware only checks the access_token cookie to allow the route or redirect to /login. The client also mirrors tokens in localStorage via token-storage for development and cross-subdomain SSO.

401 behavior

On 401 from a protected API, the axios interceptor clears storage and sends the browser to /login; login / register / forgot-password endpoints are excluded so invalid credentials do not wipe a valid session.

Project lifecycle (operations view)

1. An org admin creates a project within subscription limits (ORG_ADMIN + botApps feature).
2. Agents are defined; optionally a router splits traffic.
3. Integrations and project tools are added; KB tools reference knowledge bases.
4. The board is wired with nodes and edges.
5. Test mode simulates user messages.
6. For production, an inbox is connected and bot / live agent assignments are set; widget or channels go live.

Failures may surface as 403 / 402 or structured errors — see Subscription and Error codes.

Board node types (when to use which)

Node	When to use
Router	Split the same input to specialist agents; routing description and priority matter.
Sub-agent	Hand off work to another agent context.
Tool	Concrete action the LLM calls (API, KB search, etc.).
Integration	Shared external service; multiple tools may reuse it.
Knowledge base	Makes the RAG path visible on the board.
Inbox	Shows which platform inbox is bound to this project.

Screenshot

Full board with a selected node and the right detail panel fits well here.

Analytics vs orchestration vs projects

• Projects answer what the bot says to end users.
• Analytics agents let you ask natural-language questions about business data and dashboards.
• Orchestration runs background workflows on events (e.g. live messaging triggers), separate from chat content.

Backend module map (developers)

Nest module	Controller path (summary)	Responsibility
Auth	auth	Login, register, JWT
User	users	Profile, org list
Organization	organizations	Members, invites, switch org
Subscription	subscriptions	Plans, limits, feature flags
Projects	projects	Bot app, agents, tools, board, inbox
Knowledge base	knowledgebases	Documents, embeddings
Dashboard	dashboard	Home summaries, activity
Analytics	analytics	Dashboards, widgets, analytics agent
Reports	reports	Conversation and inbox KPI aggregates
Live messaging	(platform internal API)	Inboxes, channel mapping, customer comms
Messaging environment	(super admin)	Environment base URL and credential registry
Orchestration	orchestration	Workflow CRUD and triggers
AI autofill	ai	Autofill helpers
AI Builder	projects/:appId/builder	Natural-language project sessions
Channel events	(webhook ingress)	Processing events from external channels

Frontend route map

Nav item	Route
Home	/
Projects	/projects, detail /projects/[id]
Project chat test	/projects/[id]/chat
Knowledge bases	/knowledge-bases, detail /knowledge-bases/[id]
Analytics agents	/analytic-agents, dashboard /analytic-agents/[dashboardId]
Orchestration	/orchestration
Reports	/reports/overview, …, /reports/users
Organization	/organizations
Subscription	/subscription
Profile	/profile
Messaging environment instances	/chat-platform-instances (super admin only)

Auth routes /login, /register, /forgot-password render without the main app shell (no sidebar).

Security notes (summary)

• Do not expose tokens in support tickets or console copy-pastes.
• Keep X-Organization-Id manipulation out of untrusted client code paths.
• Privacy compliance depends on your communication channels, partners, and LLM vendor DPA — this doc is not legal advice.

Next steps

• Learning path
• Authentication
• Project management
• API authentication