Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Client (React/Vite)                      │
│                      https://localhost:3001                      │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Server (Node.js/Express)                    │
│                      https://localhost:3000                      │
├─────────────────────────────────────────────────────────────────┤
│  Routes: /user/* /chats/* /flows/* /prompts/* /admin/* /ai/*    │
│  Middleware: Auth, ACL, Logging, Error Handling                  │
└─────────────────────────────────────────────────────────────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        ▼                        ▼                        ▼
┌───────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  Azure Cosmos │      │  Azure AI Search │      │   LLM Providers │
│      DB       │      │   + Blob Storage │      │  (Multi-vendor) │
└───────────────┘      └─────────────────┘      └─────────────────┘

​

Monorepo Structure

​

API Documentation

​

Chat Types & Entity Scopes

​

1. Workspace (Ephemeral)

• Storage: Redux only (client-side state), never saved to Cosmos DB
• Lifecycle: Lost on browser close, refresh, or clear
• Files: Uploaded to Azure Blob Private/ folder by default (files persist; chat history does not). When OneDrive is enabled (personalFileLocation = OneDrive) and Document Level ACL permissions are enabled (Admin → Delegated Permissions [#/admin/delegated]), workspace files are stored in the user’s OneDrive instead.
• ACL: N/A — creator only, no shared access
• Appears in navigation: As a pinned “My Chat” item (not in the chat list)

workspaceUser = enablePersonalWorkspace AND (allowedWorkspaceUsers is empty OR user is in list)

​

2. Shared (Persisted)

• Storage: Cosmos DB (chats container)
• Lifecycle: Permanent until deleted
• Files: Azure Blob Shared/{folderName}/ with per-chat search index
• ACL: Full ACL with owners/contributors/users and inheritance
• Appears in navigation: Yes, under pages
• Default: Shared scope is always enabled (defaultEntityScopeConfig.allowShared defaults to true and cannot be fully disabled — the system falls back to shared if no scopes are allowed)

​

3. Personal (Persisted) — Rarely Used

• Storage: Cosmos DB (chats container)
• Lifecycle: Permanent until deleted
• Files: Azure Blob Personal/{sanitized-upn}/
• ACL: Creator only (no shared ACL — only the creator can see or access)
• Appears in navigation: Yes

• Global default: defaultEntityScopeConfig.allowPersonal — toggles personal scope for all entity types
• Per-type override: entityScopeOverrides.chat.allowPersonal — overrides the global default specifically for chats
• Server-side enforcement via validateEntityScope() blocks personal chat creation when disabled
• Default: allowPersonal: true for chats

⚠️ Recommendation: It is generally not recommended to allow users to create multiple personal chats as they consume an Azure AI Search index. The ephemeral workspace already provides a private chat experience without any indexing overhead. Consider disabling personal chat scope (allowPersonal: false for the Chat entity type) unless there is a specific need for persisted personal chats.

​

Comparison

​

Look & Feel

​

Branding

​

Theme

• Palette mode — Light or dark
• Primary color — Main accent color
• Secondary color — Secondary accent color
• Header color — Custom AppBar color
• Typography — Font family
• Spacing — Base spacing unit

​

Embedded Agent Mode

​

Enabling

1. Open the chat’s edit form
2. Check Embedded Agent Mode
3. An iframe embed code is automatically generated with a copy button

​

Embed Code

<iframe
  src="https://your-domain.com/path#/chat/chat-id"
  width="100%"
  height="600"
  frameborder="0"
  style="border: 1px solid #ccc; border-radius: 4px;">
</iframe>

​

Profile Sync

1. On app load, the client fetches the user’s Graph profile collections
2. Selected collections are formatted and stored as Mem0 memories in the USER_GLOBAL scope
3. The AI can then reference this context (job title, department, skills, etc.) in conversations

​

Feedback System

• Thumbs up/down — Per-message feedback buttons (individually toggleable via enableThumbsUp / enableThumbsDown)
• Detailed feedback form — Optional text box for written feedback (enableThumbsUpOrDownFeedbackTextBox)
• Feedback persistence — Stored in the feedback Cosmos DB container with message context
• Admin review — Admin → Feedback ([#/admin/feedback]) page for reviewing and analyzing all feedback
• Chat log integration — Feedback status displayed alongside chat history in logs

​

Assignments

• Target chat — The chat template (AI settings, RAG sources, memory scope, optional flow)
• Assignee — One UPN per row (groups are expanded into individual assignments)
• Completion criterion — Configurable condition that satisfies the assignment
• Due date (soft) and Expiration (hard)
• Retry budget — maxAttempts caps how many times an assignee can attempt
• Opt-in capabilities — allowDelegation, allowRejection
• Audit trail — Attempts, delegation chain, timestamps, outcome data

​

Feature Setup Guides