# tomseai/toc-chat architecture

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

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

## Overview

1. **Overall shape**
   Toc Chat is a two-app monorepo: an Angular PWA in `apps/web` and a small Node API in `apps/api`. The README emphasizes that the hosted product is primarily a static web app, with provider access configured by the user in-browser.

2. **Primary runtime boundary**
   The main architectural boundary is between the browser client and an OpenAI-compatible provider. The web app owns conversation state, rendering, branching, memory, and settings; the API layer appears to be a separate server entry point (`apps/api/src/server.ts`) rather than the central backend.

3. **Web shell and routing**
   The Angular shell starts at `apps/web/src/main.ts` and is composed through `app.config.ts`, `app.routes.ts`, and `app.ts`. This is the top-level composition layer for app-wide providers, route structure, and layout.

4. **Chat experience as the core product**
   Most feature work lives under `apps/web/src/app/chat`. The key UI surfaces are a `chat-page`, `chat-thread`, `chat-message-list`, and `chat-composer`, which together form the main interaction loop: display conversation, enter a prompt, and render responses.

5. **Workspace/domain model**
   The deepest logic is in `apps/web/src/app/core/workspace`. This layer models the conversation as a workspace with runtime state, domain rules, and flows. It contains state objects, flow orchestration, and adapters that separate the chat UI from the underlying conversation mechanics.

6. **Message and stream processing**
   Streaming is a first-class concern. Files like `message-stream`, `stream-chunk-buffer`, and `chat-provider` indicate that provider responses arrive incrementally and are normalized before entering workspace state. This is important for diagramming because message generation is not a single request/response path; it is a stream-driven pipeline.

7. **Specialized conversation flows**
   The app includes several domain flows beyond normal chat: conversation titles, topics, transfer, snapshotting, and compact-memory workflows. These are coordinated in `core/workspace/flows`, suggesting a layered pipeline where UI actions trigger flows that mutate workspace state and derived artifacts.

8. **Conversation map and navigable memory**
   A major differentiator is the “conversation map” feature under `core/map` and `chat/conversation-map`. It appears to generate or maintain a navigable structure of covered topics and short questions, enabling sidebar-style traversal through long chats rather than simple linear scrolling.

9. **Compact memory and long-chat support**
   The compact-memory subsystem spans `core/compact`, `core/workspace/domain/compact-memory-flow.ts`, and the `compact-memory-review-dialog`. This is a distinct architecture branch for summarizing or compressing older parts of a conversation so the app remains usable over long sessions.

10. **Reading, observability, and theme settings**
   User experience customization is split into dedicated subsystems: reading settings (`core/reading` and `reading-settings-dialog`), provider settings (`core/api` and `settings/provider-settings-dialog`), observability/debugging (`core/observability` and `observability-debug-dialog`), and theme support (`core/theme`). These are cross-cutting services rather than chat features.

11. **Persistence and local workspace storage**
   `core/storage/workspace-storage.ts` and related workspace utilities indicate the app persists conversation/workspace data locally in the browser. The architecture therefore relies heavily on client-side state and storage, not a centralized server database.

12. **Shared UI and interaction dialogs**
   The `shared/dialogs` folder contains reusable flows for rename, delete confirmation, edit message, and project docs. These are supporting interaction boundaries around core entities like conversations and messages, and they help keep the main chat surface uncluttered.

13. **Testing and simulation**
   The repo uses Playwright e2e tests in `tests/e2e`, with helper modules for chat, drag, and settings interactions. There are also simulation and mock scenario utilities in `core/simulation`, which suggests the app can be exercised with deterministic conversation data for development and test coverage.

14. **Delivery and deployment**
   The project is built for GitHub Pages via `.github/workflows/pages.yml`, with Angular service worker/PWA config in `apps/web/ngsw-config.json` and a web manifest under `apps/web/public`. That means the production deployment model is static hosting for the client, with offline/PWA behavior managed in the frontend.

15. **How to diagram it**
   A useful architecture diagram would place the Angular shell at the center, with the chat UI as the primary entry point, the workspace/flow engine as the domain core beneath it, local storage and provider API access as side boundaries, and auxiliary subsystems for map/memory/readability/observability branching out from the core conversation model.

Main entry points: [`apps/web/src/app/core/workspace/chat-workspace.ts`](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/workspace/chat-workspace.ts) (Workspace), [`apps/web/src/app/app.ts`](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/app.ts) (App shell), [`apps/web/src/app/chat/chat-thread/chat-thread.ts`](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/chat/chat-thread/chat-thread.ts) (Chat thread), [`apps/web/src/app/chat/chat-page/chat-page.ts`](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/chat/chat-page/chat-page.ts) (Chat page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_web["Web app"]
  node_node_main["Bootstrap<br/>angular entry<br/>[main.ts]"]
  node_node_shell["App shell<br/>angular shell<br/>[app.ts]"]
  node_node_routes["Routes<br/>routing<br/>[app.routes.ts]"]
  node_node_chat_page["Chat page<br/>feature page<br/>[chat-page.ts]"]
  node_node_chat_thread["Chat thread<br/>conversation UI<br/>[chat-thread.ts]"]
  node_node_sidebar["Sidebar<br/>navigation UI"]
  node_node_workspace[("Workspace<br/>domain core<br/>[chat-workspace.ts]")]
  node_node_flows["Flows<br/>orchestration"]
  node_node_stream["Message stream<br/>stream pipeline<br/>[message-stream.ts]"]
  node_node_provider["Provider API<br/>client adapter<br/>[chat-provider.ts]"]
  node_node_storage[("Local storage<br/>browser persistence")]
  node_node_map{{"Conversation map<br/>navigation memory"}}
  node_node_compact{{"Compact memory<br/>summarization flow"}}
  node_node_reading["Reading settings<br/>ux settings"]
  node_node_theme["Theme<br/>[theme.service.ts]"]
  node_node_observability["Observability<br/>debug telemetry"]
  node_node_shared_dialogs["Shared dialogs<br/>ui dialogs<br/>[rename-dialog.ts]"]
end

subgraph group_group_api["API"]
  node_node_api_server["API server<br/>node entry<br/>[server.ts]"]
end

subgraph group_group_quality["Quality"]
  node_node_tests["E2E tests<br/>playwright suite<br/>[chat-flow.spec.ts]"]
  node_node_simulation{{"Simulation<br/>mock scenarios"}}
end

node_node_main -->|"boots"| node_node_shell
node_node_shell -->|"configures"| node_node_routes
node_node_shell -->|"navigates to"| node_node_chat_page
node_node_shell -->|"hosts"| node_node_sidebar
node_node_chat_page -->|"contains"| node_node_chat_thread
node_node_chat_thread -->|"reads/writes"| node_node_workspace
node_node_chat_thread -->|"triggers"| node_node_flows
node_node_flows -->|"consumes"| node_node_stream
node_node_stream -->|"requests"| node_node_provider
node_node_provider -->|"feeds"| node_node_workspace
node_node_workspace -->|"persists"| node_node_storage
node_node_workspace -->|"derives"| node_node_map
node_node_workspace -->|"compresses"| node_node_compact
node_node_workspace -->|"uses"| node_node_reading
node_node_workspace -->|"reports"| node_node_observability
node_node_workspace -->|"opens"| node_node_shared_dialogs
node_node_shell -->|"styles"| node_node_theme
node_node_sidebar -->|"navigates"| node_node_map
node_node_chat_page -->|"reviews"| node_node_compact
node_node_chat_page -->|"debugs"| node_node_observability
node_node_chat_thread -->|"uses"| node_node_shared_dialogs
node_node_api_server -.->|"separate boundary"| node_node_provider
node_node_tests -->|"covers"| node_node_chat_thread
node_node_tests -->|"covers"| node_node_sidebar
node_node_simulation -->|"drives"| node_node_workspace
node_node_simulation -->|"exercises"| node_node_flows

click node_node_main "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/main.ts"
click node_node_shell "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/app.ts"
click node_node_routes "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/app.routes.ts"
click node_node_chat_page "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/chat/chat-page/chat-page.ts"
click node_node_chat_thread "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/chat/chat-thread/chat-thread.ts"
click node_node_sidebar "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/sidebar/conversation-sidebar/conversation-sidebar.ts"
click node_node_workspace "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/workspace/chat-workspace.ts"
click node_node_flows "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/workspace/flows/conversation-driver.ts"
click node_node_stream "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/workspace/flows/message-stream.ts"
click node_node_provider "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/api/chat-provider.ts"
click node_node_storage "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/storage/workspace-storage.ts"
click node_node_map "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/map/conversation-map-settings.service.ts"
click node_node_compact "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/compact/compact-memory-state.ts"
click node_node_reading "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/reading/chat-reading-settings.service.ts"
click node_node_theme "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/theme/theme.service.ts"
click node_node_observability "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/observability/observability.service.ts"
click node_node_shared_dialogs "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/shared/dialogs/rename-dialog.ts"
click node_node_api_server "https://github.com/tomseai/toc-chat/blob/main/apps/api/src/server.ts"
click node_node_tests "https://github.com/tomseai/toc-chat/blob/main/tests/e2e/chat-flow.spec.ts"
click node_node_simulation "https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/simulation/mock-conversation-scenario.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_node_main,node_node_shell,node_node_routes,node_node_chat_page,node_node_chat_thread,node_node_sidebar,node_node_workspace,node_node_flows,node_node_stream,node_node_provider,node_node_storage,node_node_map,node_node_compact,node_node_reading,node_node_theme,node_node_observability,node_node_shared_dialogs toneBlue
class node_node_api_server toneAmber
class node_node_tests,node_node_simulation toneMint
```

## Components

### Web app

Angular PWA and browser-side conversation system

- [Bootstrap](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/main.ts): angular entry · Browser app startup and root composition · `apps/web/src/main.ts`
- [App shell](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/app.ts): angular shell · Root component, routes, and app-wide providers · `apps/web/src/app/app.ts`
- [Routes](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/app.routes.ts): routing · Route map and app configuration · `apps/web/src/app/app.routes.ts`
- [Chat page](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/chat/chat-page/chat-page.ts): feature page · Top-level chat experience container · `apps/web/src/app/chat/chat-page/chat-page.ts`
- [Chat thread](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/chat/chat-thread/chat-thread.ts): conversation UI · Message list and composer interaction loop · `apps/web/src/app/chat/chat-thread/chat-thread.ts`
- [Sidebar](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/sidebar/conversation-sidebar/conversation-sidebar.ts): navigation UI · Conversation navigation and traversal · `apps/web/src/app/sidebar/conversation-sidebar/conversation-sidebar.ts`
- [Workspace](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/workspace/chat-workspace.ts): domain core · Conversation state, rules, and runtime coordination · `apps/web/src/app/core/workspace/chat-workspace.ts`
- [Flows](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/workspace/flows/conversation-driver.ts): orchestration · Chat actions transformed into workspace mutations · `apps/web/src/app/core/workspace/flows/conversation-driver.ts`
- [Message stream](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/workspace/flows/message-stream.ts): stream pipeline · Incremental provider response handling and buffering · `apps/web/src/app/core/workspace/flows/message-stream.ts`
- [Provider API](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/api/chat-provider.ts): client adapter · OpenAI-compatible provider access and request payloads · `apps/web/src/app/core/api/chat-provider.ts`
- [Local storage](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/storage/workspace-storage.ts): browser persistence · Workspace persistence in the browser · `apps/web/src/app/core/storage/workspace-storage.ts`
- [Conversation map](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/map/conversation-map-settings.service.ts): navigation memory · Topic graph and navigable conversation structure · `apps/web/src/app/core/map/conversation-map-settings.service.ts`
- [Compact memory](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/compact/compact-memory-state.ts): summarization flow · Long-chat compression and review workflow · `apps/web/src/app/core/compact/compact-memory-state.ts`
- [Reading settings](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/reading/chat-reading-settings.service.ts): ux settings · Reading and presentation preferences · `apps/web/src/app/core/reading/chat-reading-settings.service.ts`
- [Theme](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/theme/theme.service.ts): ui theme · Application theme and appearance service · `apps/web/src/app/core/theme/theme.service.ts`
- [Observability](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/observability/observability.service.ts): debug telemetry · Debugging and runtime visibility tools · `apps/web/src/app/core/observability/observability.service.ts`
- [Shared dialogs](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/shared/dialogs/rename-dialog.ts): ui dialogs · Reusable rename, delete, edit, and docs dialogs · `apps/web/src/app/shared/dialogs/rename-dialog.ts`

### API

Small Node server entry point

- [API server](https://github.com/tomseai/toc-chat/blob/main/apps/api/src/server.ts): node entry · Separate server entry point · `apps/api/src/server.ts`

### Quality

End-to-end tests and simulation support

- [E2E tests](https://github.com/tomseai/toc-chat/blob/main/tests/e2e/chat-flow.spec.ts): playwright suite · End-to-end coverage for shell, chat, branching, and settings · `tests/e2e/chat-flow.spec.ts`
- [Simulation](https://github.com/tomseai/toc-chat/blob/main/apps/web/src/app/core/simulation/mock-conversation-scenario.ts): mock scenarios · Deterministic conversation scenarios for development and testing · `apps/web/src/app/core/simulation/mock-conversation-scenario.ts`

## Connections

- Bootstrap → App shell: boots · Main entry mounts the Angular root
- App shell → Routes: configures · Root shell wires routing and providers
- App shell → Chat page: navigates to · Routes expose the chat experience
- App shell → Sidebar: hosts · Global layout includes conversation navigation
- Chat page → Chat thread: contains · Page delegates the main interaction loop
- Chat thread → Workspace: reads/writes · UI binds to workspace state and actions
- Chat thread → Flows: triggers · Composer and message actions invoke flows
- Flows → Message stream: consumes · Flows handle incremental provider output
- Message stream → Provider API: requests · Streaming pipeline calls the provider adapter
- Provider API → Workspace: feeds · Normalized responses become workspace events
- Workspace → Local storage: persists · Conversation state is stored locally
- Workspace → Conversation map: derives · Workspace state drives navigable topic structure
- Workspace → Compact memory: compresses · Long-chat memory is summarized through compact flows
- Workspace → Reading settings: uses · Workspace respects reading preferences
- Workspace → Observability: reports · Runtime emits debugging and trace information
- Workspace → Shared dialogs: opens · Workspace actions surface through shared dialogs
- App shell → Theme: styles · App shell applies theme service
- Sidebar → Conversation map: navigates · Sidebar presents the conversation map
- Chat page → Compact memory: reviews · Chat UI can launch compact-memory review
- Chat page → Observability: debugs · Debug dialog is available from the chat surface
- Chat thread → Shared dialogs: uses · Message editing and renaming rely on shared dialogs
- API server → Provider API: separate boundary · Server exists as an auxiliary runtime, not the main loop
- E2E tests → Chat thread: covers · End-to-end flows exercise the chat interaction
- E2E tests → Sidebar: covers · Tests verify navigation and branching behavior
- Simulation → Workspace: drives · Mock scenarios feed deterministic workspace state
- Simulation → Flows: exercises · Automation scenarios run through the same flow layer
