# deco-cx/chat architecture

> Architecture diagram of the GitHub repository deco-cx/chat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deco-cx/chat
- Repository: https://github.com/deco-cx/chat

## Overview

##### Project Type and Purpose
- deco.chat is a full-stack, open-source AI workspace platform that lets teams spin up rich, UI-driven chat agents.
- It is organized as a monorepo with:
- A React/Vite frontend (“apps/web”),
- A Deno‐based HTTP API (“apps/api”),
- A Cloudflare Worker–style outbound service (“apps/outbound”),
- A CLI client (“packages/cli”),
- Core shared libraries for AI logic (“packages/ai”), runtime hosting (“packages/runtime”), SDK and hooks (“packages/sdk”), and UI primitives (“packages/ui”),
- A Supabase schema/migration folder.

##### File Structure
- apps/web: React + Vite application, lots of components, hooks, assets, environment configuration.
- apps/api: Deno + Oak (or built‐in) HTTP entrypoint, middlewares for auth, context, Stripe webhooks, database utils, actors.
- apps/outbound: a small Deno/Cloudflare Worker that handles outbound channel calls (e.g., WhatsApp, Slack).
- packages/cli: Deno-powered CLI to manage auth, deploy, link, whoami, MCP publishing.
- packages/ai: Core TypeScript agent runtime, triggers, tools, MCP loaders, message adapters.
- packages/runtime: JSR bindings, proxy, connection abstractions for hosting agents.
- packages/sdk: HTTP client and React hooks for app/web to call the API, auth flows, cache, observability.
- packages/ui: Tailwind/CSS + React primitives used by apps/web and example agent UIs.
- supabase/: Database migrations and policies for Supabase Postgres.

##### README for Additional Insights
- Describes production vs. local environment flags.
- Mentions Deno + Node prerequisites, CLI installation, Supabase migrations.
- Key functional domains: interactive chat, “Golden Layout” multitabs, extensible MCP catalog, community library.
- External integrations: Stripe (billing/webhooks), Supabase (data + auth), 3rd-party APIs (via MCP).

##### Detail Is Key
- In the Shared Libraries lane, list: packages/ai, packages/runtime, packages/sdk, packages/ui.
- Supabase schema folder under Database.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        direction TB
        Browser["User Browser"]:::external
        FrontendUI["Frontend UI\n(React/Vite)"]:::client
        CLI["CLI Client"]:::client
    end

    %% Serverless/Services Layer
    subgraph "Serverless/Services"
        direction TB
        APIServer["API Server\n(Deno HTTP)"]:::service
        Outbound["Outbound Worker\n(Cloudflare)"]:::service
    end

    %% Shared Libraries Layer
    subgraph "Shared Libraries"
        direction TB
        AIRuntime["AI Runtime\n(packages/ai)"]:::shared
        HostingRuntime["Hosting Runtime\n(packages/runtime)"]:::shared
        SDKLib["SDK & Hooks\n(packages/sdk)"]:::shared
        UILib["UI Primitives\n(packages/ui)"]:::shared
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        SupabaseDB["Supabase\n(Postgres/Migrations)"]:::infra
        ExternalServices["External Services\n(Stripe, 3rd-party APIs)"]:::infra
    end

    %% Data Flows
    Browser -->|"interacts with"| FrontendUI
    FrontendUI -->|"uses SDK hooks"| SDKLib
    FrontendUI -->|"uses UI primitives"| UILib
    SDKLib -->|"HTTP calls"| APIServer
    CLI -->|"management APIs"| APIServer
    CLI -->|"direct DB access"| SupabaseDB
    APIServer -->|"reads/writes"| SupabaseDB
    APIServer -->|"invokes"| Outbound
    APIServer -->|"billing webhooks"| ExternalServices
    Outbound -->|"push events"| ExternalServices
    APIServer -->|"orchestrates AI"| AIRuntime
    APIServer -->|"uses hosting"| HostingRuntime
    SDKLib -->|"exposes client logic"| AIRuntime
    SDKLib -->|"observability hooks"| HostingRuntime

    %% Click Events
    click FrontendUI "https://github.com/deco-cx/chat/tree/main/apps/web"
    click APIServer "https://github.com/deco-cx/chat/tree/main/apps/api"
    click Outbound "https://github.com/deco-cx/chat/tree/main/apps/outbound"
    click CLI "https://github.com/deco-cx/chat/tree/main/packages/cli"
    click AIRuntime "https://github.com/deco-cx/chat/tree/main/packages/ai"
    click HostingRuntime "https://github.com/deco-cx/chat/tree/main/packages/runtime"
    click SDKLib "https://github.com/deco-cx/chat/tree/main/packages/sdk"
    click UILib "https://github.com/deco-cx/chat/tree/main/packages/ui"
    click SupabaseDB "https://github.com/deco-cx/chat/tree/main/supabase"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:2px;
    classDef service fill:#DFF2D8,stroke:#22863A,color:#22863A,stroke-width:2px;
    classDef shared fill:#FFE8D6,stroke:#D15704,color:#D15704,stroke-width:2px;
    classDef infra fill:#F1F8FF,stroke:#6A737D,color:#6A737D,stroke-width:2px;
    classDef external fill:#EFEFEF,stroke:#999999,color:#555555,stroke-width:1px,stroke-dasharray: 5 5;
```
