How tomseai/toc-chat works
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: chat-workspace.ts Workspace · app.ts App shell · chat-thread.ts Chat thread · chat-page.ts Chat page
Components 20
Web app
Angular PWA and browser-side conversation system
- Bootstrap · Browser app startup and root composition
apps/web/src/main.ts - App shell · Root component, routes, and app-wide providers
apps/web/src/app/app.ts - Routes · Route map and app configuration
apps/web/src/app/app.routes.ts - Chat page · Top-level chat experience container
apps/web/src/app/chat/chat-page/chat-page.ts - Chat thread · Message list and composer interaction loop
apps/web/src/app/chat/chat-thread/chat-thread.ts - Sidebar · Conversation navigation and traversal
apps/web/src/app/sidebar/conversation-sidebar/conversation-sidebar.ts - Workspace · Conversation state, rules, and runtime coordination
apps/web/src/app/core/workspace/chat-workspace.ts - Flows · Chat actions transformed into workspace mutations
apps/web/src/app/core/workspace/flows/conversation-driver.ts - Message stream · Incremental provider response handling and buffering
apps/web/src/app/core/workspace/flows/message-stream.ts - Provider API · OpenAI-compatible provider access and request payloads
apps/web/src/app/core/api/chat-provider.ts - Local storage · Workspace persistence in the browser
apps/web/src/app/core/storage/workspace-storage.ts - Conversation map · Topic graph and navigable conversation structure
apps/web/src/app/core/map/conversation-map-settings.service.ts - Compact memory · Long-chat compression and review workflow
apps/web/src/app/core/compact/compact-memory-state.ts - Reading settings · Reading and presentation preferences
apps/web/src/app/core/reading/chat-reading-settings.service.ts - Theme · Application theme and appearance service
apps/web/src/app/core/theme/theme.service.ts - Observability · Debugging and runtime visibility tools
apps/web/src/app/core/observability/observability.service.ts - Shared dialogs · Reusable rename, delete, edit, and docs dialogs
apps/web/src/app/shared/dialogs/rename-dialog.ts
Quality
End-to-end tests and simulation support
- E2E tests · End-to-end coverage for shell, chat, branching, and settings
tests/e2e/chat-flow.spec.ts - Simulation · Deterministic conversation scenarios for development and testing
apps/web/src/app/core/simulation/mock-conversation-scenario.ts
Connections 26
- 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