# boson-chat/boson architecture

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

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

## Overview

Boson is a desktop IRC chat application with a Preact renderer, an in-process Go IRC engine, and a companion HTTP API for accounts, directory, sessions, presence, and related services. The main user flow is sign-in or guest entry, server discovery or manual setup, IRC connection and chat, with local history and account-linked features. The monorepo also includes a standalone marketing website and shared design system. Several subsystem paths are documented but unsampled; their internal connections are therefore not expanded.

Main entry points: [`backend/http/server.go`](https://github.com/boson-chat/boson/blob/main/backend/http/server.go) (HTTP API), [`client/src/renderer/src/app.tsx`](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/app.tsx) (App shell), [`client/src/renderer/src/screens/DirectoryScreen/DirectoryScreen.tsx`](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/screens/DirectoryScreen/DirectoryScreen.tsx) (Server directory), [`client/src/renderer/src/modules/engine/engine.client.ts`](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/engine/engine.client.ts) (Engine client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat client"]
  node_renderer["App shell<br/>[app.tsx]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_identity["Encrypted identity"]
  node_secure["Secure storage<br/>[secure-storage.ts]"]
  node_directory["Server directory"]
  node_directoryservice["Directory API client"]
  node_chat["Chat operations<br/>[chat.service.ts]"]
  node_history[("Chat history")]
  node_memos[("Inbox memos<br/>[memo.store.ts]")]
  node_engineclient["Engine client<br/>[engine.client.ts]"]
end

subgraph group_runtime["IRC runtime"]
  node_desktop["Desktop shell<br/>[engine.go]"]
  node_securebridge["OS secure store<br/>[securestore.go]"]
  node_ipc["Engine IPC<br/>[server.go]"]
  node_irc["IRC connections<br/>[client.go]"]
end

subgraph group_backend["Account services"]
  node_backendapi["HTTP API<br/>[server.go]"]
  node_users["User service<br/>[repository.go]"]
  node_servers["Directory service<br/>[service.go]"]
  node_sessions["Session service<br/>[service.go]"]
  node_presence["Presence service<br/>[service.go]"]
  node_nickclaim["Nick claims<br/>[pop3_worker.go]"]
  node_database[("Postgres<br/>[db.go]")]
end

subgraph group_web["Public website"]
  node_website["Marketing site<br/>[app.tsx]"]
  node_webpages["Public pages<br/>[FeaturesPage.tsx]"]
  node_release["Release lookup"]
end

node_user(("User"))
node_supabase["Supabase Auth"]
node_github["GitHub releases"]

node_user -->|"uses"| node_renderer
node_renderer -->|"initializes"| node_auth
node_auth -->|"authenticates"| node_supabase
node_renderer -->|"renders"| node_directory
node_directory -.->|"uses"| node_directoryservice
node_directoryservice -.->|"requests"| node_backendapi
node_renderer -->|"restores identity"| node_identity
node_identity -.->|"persists secrets"| node_secure
node_user -->|"selects server"| node_directory
node_directory -.->|"starts chat"| node_chat
node_chat -.->|"commands"| node_engineclient
node_engineclient -->|"sends frames"| node_desktop
node_desktop -->|"serves session"| node_ipc
node_engineclient -.->|"controls via IPC"| node_irc
node_ipc -->|"dispatches commands"| node_irc
node_irc -.->|"streams events"| node_engineclient
node_chat -.->|"stores history"| node_history
node_renderer -->|"reads memos"| node_memos
node_backendapi -->|"routes requests"| node_users
node_backendapi -->|"routes requests"| node_servers
node_backendapi -->|"routes requests"| node_sessions
node_backendapi -->|"routes requests"| node_presence
node_backendapi -->|"starts worker"| node_nickclaim
node_users -.->|"reads and writes"| node_database
node_servers -.->|"reads and writes"| node_database
node_website -->|"routes pages"| node_webpages
node_webpages -->|"reads release"| node_release
node_release -->|"fetches release"| node_github

click node_renderer "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/app.tsx"
click node_auth "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/auth/auth.service.ts"
click node_identity "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/identity/identity.service.ts"
click node_secure "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/shared/secure-storage.ts"
click node_directory "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/screens/DirectoryScreen/DirectoryScreen.tsx"
click node_directoryservice "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/directory/directory.service.ts"
click node_chat "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/chat/chat.service.ts"
click node_history "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/history/idb-chat-history.store.ts"
click node_memos "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/memos/memo.store.ts"
click node_engineclient "https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/engine/engine.client.ts"
click node_desktop "https://github.com/boson-chat/boson/blob/main/desktop/engine.go"
click node_securebridge "https://github.com/boson-chat/boson/blob/main/desktop/securestore.go"
click node_ipc "https://github.com/boson-chat/boson/blob/main/engine/ipc/server.go"
click node_irc "https://github.com/boson-chat/boson/blob/main/engine/irc/client.go"
click node_backendapi "https://github.com/boson-chat/boson/blob/main/backend/http/server.go"
click node_users "https://github.com/boson-chat/boson/blob/main/backend/internal/services/user/repository.go"
click node_servers "https://github.com/boson-chat/boson/blob/main/backend/internal/services/server/service.go"
click node_sessions "https://github.com/boson-chat/boson/blob/main/backend/internal/services/session/service.go"
click node_presence "https://github.com/boson-chat/boson/blob/main/backend/internal/services/presence/service.go"
click node_nickclaim "https://github.com/boson-chat/boson/blob/main/backend/internal/services/nickclaim/pop3_worker.go"
click node_database "https://github.com/boson-chat/boson/blob/main/backend/internal/db/db.go"
click node_website "https://github.com/boson-chat/boson/blob/main/website/src/app.tsx"
click node_webpages "https://github.com/boson-chat/boson/blob/main/website/src/pages/FeaturesPage.tsx"
click node_release "https://github.com/boson-chat/boson/blob/main/website/src/hooks/useLatestRelease.ts"

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_renderer,node_auth,node_identity,node_secure,node_directory,node_directoryservice,node_chat,node_history,node_memos,node_engineclient,node_user toneBlue
class node_desktop,node_securebridge,node_ipc,node_irc toneAmber
class node_backendapi,node_users,node_servers,node_sessions,node_presence,node_nickclaim,node_database toneMint
class node_website,node_webpages,node_release toneRose
class node_supabase,node_github toneIndigo
```

## Components

### Chat client

- [App shell](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/app.tsx): `client/src/renderer/src/app.tsx`
- [Authentication](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/auth/auth.service.ts): `client/src/renderer/src/modules/auth/auth.service.ts`
- [Encrypted identity](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/identity/identity.service.ts): `client/src/renderer/src/modules/identity/identity.service.ts`
- [Secure storage](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/shared/secure-storage.ts): `client/src/renderer/src/shared/secure-storage.ts`
- [Server directory](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/screens/DirectoryScreen/DirectoryScreen.tsx): `client/src/renderer/src/screens/DirectoryScreen/DirectoryScreen.tsx`
- [Directory API client](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/directory/directory.service.ts): `client/src/renderer/src/modules/directory/directory.service.ts`
- [Chat operations](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/chat/chat.service.ts): `client/src/renderer/src/modules/chat/chat.service.ts`
- [Chat history](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/history/idb-chat-history.store.ts): `client/src/renderer/src/modules/history/idb-chat-history.store.ts`
- [Inbox memos](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/memos/memo.store.ts): `client/src/renderer/src/modules/memos/memo.store.ts`
- [Engine client](https://github.com/boson-chat/boson/blob/main/client/src/renderer/src/modules/engine/engine.client.ts): `client/src/renderer/src/modules/engine/engine.client.ts`

### IRC runtime

- [Desktop shell](https://github.com/boson-chat/boson/blob/main/desktop/engine.go): `desktop/engine.go`
- [OS secure store](https://github.com/boson-chat/boson/blob/main/desktop/securestore.go): `desktop/securestore.go`
- [Engine IPC](https://github.com/boson-chat/boson/blob/main/engine/ipc/server.go): `engine/ipc/server.go`
- [IRC connections](https://github.com/boson-chat/boson/blob/main/engine/irc/client.go): `engine/irc/client.go`

### Account services

- [HTTP API](https://github.com/boson-chat/boson/blob/main/backend/http/server.go): `backend/http/server.go`
- [User service](https://github.com/boson-chat/boson/blob/main/backend/internal/services/user/repository.go): `backend/internal/services/user/repository.go`
- [Directory service](https://github.com/boson-chat/boson/blob/main/backend/internal/services/server/service.go): `backend/internal/services/server/service.go`
- [Session service](https://github.com/boson-chat/boson/blob/main/backend/internal/services/session/service.go): `backend/internal/services/session/service.go`
- [Presence service](https://github.com/boson-chat/boson/blob/main/backend/internal/services/presence/service.go): `backend/internal/services/presence/service.go`
- [Nick claims](https://github.com/boson-chat/boson/blob/main/backend/internal/services/nickclaim/pop3_worker.go): `backend/internal/services/nickclaim/pop3_worker.go`
- [Postgres](https://github.com/boson-chat/boson/blob/main/backend/internal/db/db.go): `backend/internal/db/db.go`

### Public website

- [Marketing site](https://github.com/boson-chat/boson/blob/main/website/src/app.tsx): `website/src/app.tsx`
- [Public pages](https://github.com/boson-chat/boson/blob/main/website/src/pages/FeaturesPage.tsx): `website/src/pages/FeaturesPage.tsx`
- [Release lookup](https://github.com/boson-chat/boson/blob/main/website/src/hooks/useLatestRelease.ts): `website/src/hooks/useLatestRelease.ts`

### Other components

- **User**
- **Supabase Auth**
- **GitHub releases**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → Authentication: initializes (evidence: `client/src/renderer/src/app.tsx`)
- Authentication → Supabase Auth: authenticates (evidence: `client/src/renderer/src/modules/auth/auth.service.ts`)
- App shell → Server directory: renders (evidence: `client/src/renderer/src/app.tsx`)
- Server directory → Directory API client: uses
- Directory API client → HTTP API: requests
- App shell → Encrypted identity: restores identity (evidence: `client/src/renderer/src/app.tsx`)
- Encrypted identity → Secure storage: persists secrets
- User → Server directory: selects server (evidence: `README.md`)
- Server directory → Chat operations: starts chat
- Chat operations → Engine client: commands
- Engine client → Desktop shell: sends frames (evidence: `desktop/engine.go`)
- Desktop shell → Engine IPC: serves session (evidence: `desktop/engine.go`)
- Engine client → IRC connections: controls via IPC
- Engine IPC → IRC connections: dispatches commands (evidence: `engine/ipc/server.go`)
- IRC connections → Engine client: streams events
- Chat operations → Chat history: stores history
- App shell → Inbox memos: reads memos (evidence: `client/src/renderer/src/app.tsx`)
- HTTP API → User service: routes requests (evidence: `backend/http/server.go`)
- HTTP API → Directory service: routes requests (evidence: `backend/http/server.go`)
- HTTP API → Session service: routes requests (evidence: `backend/http/server.go`)
- HTTP API → Presence service: routes requests (evidence: `backend/http/server.go`)
- HTTP API → Nick claims: starts worker (evidence: `backend/http/server.go`)
- User service → Postgres: reads and writes
- Directory service → Postgres: reads and writes
- Marketing site → Public pages: routes pages (evidence: `website/src/app.tsx`)
- Public pages → Release lookup: reads release
- Release lookup → GitHub releases: fetches release (evidence: `website/src/hooks/useLatestRelease.ts`)