# chattocorp/chatto architecture

> Architecture diagram of the GitHub repository chattocorp/chatto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chattocorp/chatto
- Repository: https://github.com/chattocorp/chatto

## Overview

Chatto is a self-hostable team and community chat product: users enter through the web or desktop client, authenticate, then use server-backed chat and collaboration features. The repository also contains separately described client, bot, workflow, and identity products. The map preserves those documented branches; source excerpts provide only a few implementation-level links, so other connections are limited to README claims or left unasserted.

Main entry points: [`apps/desktop/main.mjs`](https://github.com/chattocorp/chatto/blob/main/apps/desktop/main.mjs) (Desktop runtime), [`cli`](https://github.com/chattocorp/chatto/tree/main/cli) (Chat server and CLI), [`apps/frontend/src/lib`](https://github.com/chattocorp/chatto/tree/main/apps/frontend/src/lib) (Web frontend), [`packages/chatto-client/src/client.ts`](https://github.com/chattocorp/chatto/blob/main/packages/chatto-client/src/client.ts) (TypeScript client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chatto application"]
  node_frontend["Web frontend"]
  node_query["Query cache<br/>[queryClient.ts]"]
  node_server["Chat server and CLI"]
  node_serverstate[("Server state provisioning<br/>[storage.go]")]
end

subgraph group_desktop["Desktop client"]
  node_desktopapp["Desktop runtime<br/>[main.mjs]"]
  node_desktopprotocol["Frontend protocol"]
  node_capture["Game capture<br/>[game_capture.mjs]"]
  node_screen["Screen sharing<br/>[screen_sharing.mjs]"]
  node_updates["Desktop updates<br/>[updates.mjs]"]
end

subgraph group_identity["Identity and APIs"]
  node_authling["Authling identity provider<br/>[main.go]"]
  node_oidc["OIDC state storage<br/>[storage.go]"]
  node_authstate[("Authling runtime storage<br/>[storage.go]")]
  node_apischema["Public API definitions"]
end

subgraph group_integrations["Clients and integrations"]
  node_client["TypeScript client<br/>[client.ts]"]
  node_chatbot["ChattoBot"]
end

subgraph group_workflow["Workflow orchestration"]
  node_runling["Runling orchestrator<br/>[source-manager.ts]"]
  node_runlingweb["Runling web routes"]
end

node_user(("Chat user"))
node_nats[("NATS JetStream")]

node_user -->|"uses"| node_frontend
node_frontend -->|"uses server"| node_server
node_user -.->|"uses"| node_desktopapp
node_desktopapp -->|"registers protocol"| node_desktopprotocol
node_desktopapp -->|"configures capture"| node_capture
node_desktopapp -->|"configures sharing"| node_screen
node_desktopapp -.->|"supports updates"| node_updates
node_frontend -.->|"uses cache"| node_query
node_query -->|"clears user stores"| node_client
node_server -.->|"provisions state"| node_serverstate
node_serverstate -->|"creates resources"| node_nats
node_authling -.->|"provides identity"| node_oidc
node_oidc -->|"uses storage"| node_authstate
node_authstate -->|"provisions buckets"| node_nats
node_client -->|"connects to"| node_server
node_chatbot -->|"built with"| node_client
node_runling -.->|"serves routes"| node_runlingweb
node_runling -.->|"orchestrates assistant"| node_chatbot
node_server -.->|"implements public API"| node_apischema

click node_frontend "https://github.com/chattocorp/chatto/tree/main/apps/frontend/src/lib"
click node_query "https://github.com/chattocorp/chatto/blob/main/apps/frontend/src/lib/query/queryClient.ts"
click node_server "https://github.com/chattocorp/chatto/tree/main/cli"
click node_serverstate "https://github.com/chattocorp/chatto/blob/main/cli/internal/core/storage.go"
click node_desktopapp "https://github.com/chattocorp/chatto/blob/main/apps/desktop/main.mjs"
click node_desktopprotocol "https://github.com/chattocorp/chatto/blob/main/apps/desktop/frontend_protocol.mjs"
click node_capture "https://github.com/chattocorp/chatto/blob/main/apps/desktop/game_capture.mjs"
click node_screen "https://github.com/chattocorp/chatto/blob/main/apps/desktop/screen_sharing.mjs"
click node_updates "https://github.com/chattocorp/chatto/blob/main/apps/desktop/updates.mjs"
click node_authling "https://github.com/chattocorp/chatto/blob/main/authling/cmd/authling/main.go"
click node_oidc "https://github.com/chattocorp/chatto/blob/main/authling/internal/oidcprovider/storage.go"
click node_authstate "https://github.com/chattocorp/chatto/blob/main/authling/internal/storage/storage.go"
click node_apischema "https://github.com/chattocorp/chatto/tree/main/proto"
click node_client "https://github.com/chattocorp/chatto/blob/main/packages/chatto-client/src/client.ts"
click node_chatbot "https://github.com/chattocorp/chatto/tree/main/packages/chattobot"
click node_runling "https://github.com/chattocorp/chatto/blob/main/packages/runling/src/runtime/source-manager.ts"
click node_runlingweb "https://github.com/chattocorp/chatto/tree/main/packages/runling/src/routes"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_query,node_server,node_serverstate,node_user toneBlue
class node_desktopapp,node_desktopprotocol,node_capture,node_screen,node_updates,node_nats toneAmber
class node_authling,node_oidc,node_authstate,node_apischema toneMint
class node_client,node_chatbot toneRose
class node_runling,node_runlingweb toneIndigo
```

## Components

### Chatto application

- [Web frontend](https://github.com/chattocorp/chatto/tree/main/apps/frontend/src/lib): `apps/frontend/src/lib`
- [Query cache](https://github.com/chattocorp/chatto/blob/main/apps/frontend/src/lib/query/queryClient.ts): `apps/frontend/src/lib/query/queryClient.ts`
- [Chat server and CLI](https://github.com/chattocorp/chatto/tree/main/cli): `cli`
- [Server state provisioning](https://github.com/chattocorp/chatto/blob/main/cli/internal/core/storage.go): `cli/internal/core/storage.go`

### Desktop client

- [Desktop runtime](https://github.com/chattocorp/chatto/blob/main/apps/desktop/main.mjs): `apps/desktop/main.mjs`
- [Frontend protocol](https://github.com/chattocorp/chatto/blob/main/apps/desktop/frontend_protocol.mjs): `apps/desktop/frontend_protocol.mjs`
- [Game capture](https://github.com/chattocorp/chatto/blob/main/apps/desktop/game_capture.mjs): `apps/desktop/game_capture.mjs`
- [Screen sharing](https://github.com/chattocorp/chatto/blob/main/apps/desktop/screen_sharing.mjs): `apps/desktop/screen_sharing.mjs`
- [Desktop updates](https://github.com/chattocorp/chatto/blob/main/apps/desktop/updates.mjs): `apps/desktop/updates.mjs`

### Identity and APIs

- [Authling identity provider](https://github.com/chattocorp/chatto/blob/main/authling/cmd/authling/main.go): `authling/cmd/authling/main.go`
- [OIDC state storage](https://github.com/chattocorp/chatto/blob/main/authling/internal/oidcprovider/storage.go): `authling/internal/oidcprovider/storage.go`
- [Authling runtime storage](https://github.com/chattocorp/chatto/blob/main/authling/internal/storage/storage.go): `authling/internal/storage/storage.go`
- [Public API definitions](https://github.com/chattocorp/chatto/tree/main/proto): `proto`

### Clients and integrations

- [TypeScript client](https://github.com/chattocorp/chatto/blob/main/packages/chatto-client/src/client.ts): `packages/chatto-client/src/client.ts`
- [ChattoBot](https://github.com/chattocorp/chatto/tree/main/packages/chattobot): `packages/chattobot`

### Workflow orchestration

- [Runling orchestrator](https://github.com/chattocorp/chatto/blob/main/packages/runling/src/runtime/source-manager.ts): `packages/runling/src/runtime/source-manager.ts`
- [Runling web routes](https://github.com/chattocorp/chatto/tree/main/packages/runling/src/routes): `packages/runling/src/routes`

### Other components

- **Chat user**
- **NATS JetStream**

## Connections

- Chat user → Web frontend: uses (evidence: `README.md`)
- Web frontend → Chat server and CLI: uses server (evidence: `README.md`)
- Chat user → Desktop runtime: uses
- Desktop runtime → Frontend protocol: registers protocol (evidence: `apps/desktop/main.mjs`)
- Desktop runtime → Game capture: configures capture (evidence: `apps/desktop/main.mjs`)
- Desktop runtime → Screen sharing: configures sharing (evidence: `apps/desktop/main.mjs`)
- Desktop runtime → Desktop updates: supports updates (evidence: `apps/desktop/main.mjs`)
- Web frontend → Query cache: uses cache (evidence: `apps/frontend/src/lib/query/queryClient.ts`)
- Query cache → TypeScript client: clears user stores (evidence: `apps/frontend/src/lib/query/queryClient.ts`)
- Chat server and CLI → Server state provisioning: provisions state (evidence: `cli/internal/core/storage.go`)
- Server state provisioning → NATS JetStream: creates resources (evidence: `cli/internal/core/storage.go`)
- Authling identity provider → OIDC state storage: provides identity
- OIDC state storage → Authling runtime storage: uses storage (evidence: `authling/internal/oidcprovider/storage.go`)
- Authling runtime storage → NATS JetStream: provisions buckets (evidence: `authling/internal/storage/storage.go`)
- TypeScript client → Chat server and CLI: connects to (evidence: `README.md`)
- ChattoBot → TypeScript client: built with (evidence: `README.md`)
- Runling orchestrator → Runling web routes: serves routes
- Runling orchestrator → ChattoBot: orchestrates assistant
- Chat server and CLI → Public API definitions: implements public API