# hugger-mugger/spur-ai-chat-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/hugger-mugger/spur-ai-chat-assistant
- Repository: https://github.com/hugger-mugger/spur-ai-chat-assistant

## Overview

1. This is a two-package monorepo with a clear frontend/backend split. The root mainly holds repo-level metadata and a semantic review note; the actual runtime systems live under `backend/` and `frontend/`.

2. The frontend is a Svelte-based single-page chat widget. `frontend/src/App.svelte` and `frontend/src/lib/ChatWidget.svelte` form the user-facing shell, while `MessageBubble.svelte` renders individual messages and `app.css` provides global styling via Tailwind/Vite.

3. The frontend’s main state boundary is client persistence. `frontend/src/lib/api.ts` is the network boundary to the backend, and `localStorage` is used to retain the active `sessionId` and cached conversation state across reloads so the UI can restore a chat without server-side auth.

4. The backend is an Express API written in TypeScript. `backend/src/index.ts` is the server entry point, with controllers split by concern: `chatController.ts` handles message submission and LLM replies, and `historyController.ts` serves chronological conversation history.

5. Request validation and error handling are centralized at the API edge. `backend/src/middleware/validation.ts` enforces input contracts before business logic runs, and `backend/src/middleware/errorHandler.ts` normalizes failures into consistent client responses instead of leaking internal stack traces.

6. The core business logic is service-oriented. `backend/src/services/llmService.ts` is the external AI boundary, and `backend/src/services/databaseService.ts` is the persistence boundary; controllers orchestrate these services rather than talking directly to the database or model provider.

7. Conversation state is stored in Prisma-managed SQLite tables. `backend/prisma/schema.prisma` and the migration folder define a `Conversation`-to-`Message` relationship, with messages indexed by conversation and timestamp so history can be fetched in order and older chats can be paginated.

8. The key data flow is: user types a message in the Svelte widget, the frontend POSTs it through `api.ts`, the backend validates and either reuses or creates a conversation, `llmService` generates a reply using prior message context, and `databaseService` persists both the user message and AI response before the response is returned to the UI.

9. The retrieval flow is separate from the send flow. On reload or session restore, the frontend calls the history endpoint, the backend queries messages for the stored `sessionId`, sorts them chronologically, and returns them so the widget can reconstruct the thread exactly as it was.

10. Configuration is environment-driven on both sides. `backend/src/config/index.ts` centralizes server/runtime settings such as ports and API keys, while the frontend uses a build-time env variable for the backend base URL; this keeps deployment targets decoupled.

11. The build/runtime boundary is straightforward: backend TypeScript compiles to `backend/dist` and runs as a Node/Express server, while the frontend is bundled by Vite into `frontend/dist` for static hosting. That makes the deployment model “API server + static client.”

12. The architectural emphasis is on a thin UI, a stateless-ish API layer, and durable conversation storage. Most of the complexity sits in the orchestration between context-aware LLM calls, message persistence, and session reuse rather than in UI routing or multi-service infrastructure.

Main entry points: [`backend/src/index.ts`](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/index.ts) (API server), [`frontend/src/lib/ChatWidget.svelte`](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/lib/ChatWidget.svelte) (Chat widget), [`backend/src/services/databaseService.ts`](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/services/databaseService.ts) (Database service), [`backend/src/controllers/chatController.ts`](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/controllers/chatController.ts) (Chat controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_shell["App shell<br/>svelte app<br/>[App.svelte]"]
  node_chat_widget["Chat widget<br/>ui component<br/>[ChatWidget.svelte]"]
  node_message_bubble["Message bubble<br/>ui component"]
  node_api_client["API client<br/>network boundary<br/>[api.ts]"]
  node_session_store[("Session cache<br/>localStorage state")]
  node_frontend_styles["App styles<br/>tailwind/css<br/>[app.css]"]
  node_vite_build["Vite build<br/>bundler<br/>[vite.config.js]"]
end

subgraph group_backend["Backend"]
  node_server_entry["API server<br/>express entry<br/>[index.ts]"]
  node_chat_controller["Chat controller<br/>request handler<br/>[chatController.ts]"]
  node_history_controller["History controller<br/>request handler"]
  node_validation_mw["Validation<br/>middleware<br/>[validation.ts]"]
  node_error_mw["Error handler<br/>middleware<br/>[errorHandler.ts]"]
  node_llm_service["LLM service<br/>ai boundary<br/>[llmService.ts]"]
  node_db_service["Database service<br/>persistence boundary<br/>[databaseService.ts]"]
  node_runtime_config["Runtime config<br/>env config<br/>[index.ts]"]
  node_prisma_schema["Prisma schema<br/>data model<br/>[schema.prisma]"]
  node_db_migrations["Migrations<br/>schema history<br/>[migration.sql]"]
end

subgraph group_repo["Repo"]
  node_repo_readme["README<br/>docs<br/>[README.md]"]
  node_semantic_review["Review note<br/>analysis"]
end

node_app_shell -->|"renders"| node_chat_widget
node_chat_widget -->|"composes"| node_message_bubble
node_chat_widget -->|"calls"| node_api_client
node_chat_widget -->|"persists"| node_session_store
node_app_shell -->|"styles"| node_frontend_styles
node_vite_build -->|"bundles"| node_app_shell
node_server_entry -->|"guards"| node_validation_mw
node_server_entry -->|"handles errors"| node_error_mw
node_server_entry -->|"routes"| node_chat_controller
node_server_entry -->|"routes"| node_history_controller
node_chat_controller -->|"generates"| node_llm_service
node_chat_controller -->|"stores"| node_db_service
node_history_controller -->|"reads"| node_db_service
node_db_service -->|"maps to"| node_prisma_schema
node_db_service -->|"evolves via"| node_db_migrations
node_runtime_config -->|"configures"| node_server_entry
node_runtime_config -->|"configures"| node_llm_service
node_api_client -->|"requests"| node_server_entry

click node_repo_readme "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/README.md"
click node_semantic_review "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/semantic-review/2025-01-sprint2-llm-context-integration.md"
click node_app_shell "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/App.svelte"
click node_chat_widget "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/lib/ChatWidget.svelte"
click node_message_bubble "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/lib/MessageBubble.svelte"
click node_api_client "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/lib/api.ts"
click node_frontend_styles "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/app.css"
click node_vite_build "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/vite.config.js"
click node_server_entry "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/index.ts"
click node_chat_controller "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/controllers/chatController.ts"
click node_history_controller "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/controllers/historyController.ts"
click node_validation_mw "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/middleware/validation.ts"
click node_error_mw "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/middleware/errorHandler.ts"
click node_llm_service "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/services/llmService.ts"
click node_db_service "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/services/databaseService.ts"
click node_runtime_config "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/config/index.ts"
click node_prisma_schema "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/prisma/schema.prisma"
click node_db_migrations "https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/prisma/migrations/20260623060511_init/migration.sql"

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_app_shell,node_chat_widget,node_message_bubble,node_api_client,node_session_store,node_frontend_styles,node_vite_build toneBlue
class node_server_entry,node_chat_controller,node_history_controller,node_validation_mw,node_error_mw,node_llm_service,node_db_service,node_runtime_config,node_prisma_schema,node_db_migrations toneAmber
class node_repo_readme,node_semantic_review toneMint
```

## Components

### Frontend

Svelte/Vite client that renders the chat widget and restores conversation state locally.

- [App shell](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/App.svelte): svelte app · Top-level Svelte entry that mounts the chat experience. · `frontend/src/App.svelte`
- [Chat widget](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/lib/ChatWidget.svelte): ui component · Main chat interface and local session restoration logic. · `frontend/src/lib/ChatWidget.svelte`
- [Message bubble](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/lib/MessageBubble.svelte): ui component · Renders individual user and assistant messages. · `frontend/src/lib/MessageBubble.svelte`
- [API client](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/lib/api.ts): network boundary · Frontend wrapper for backend chat and history requests. · `frontend/src/lib/api.ts`
- **Session cache**: localStorage state · Persists sessionId and cached conversation state across reloads.
- [App styles](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/src/app.css): tailwind/css · Global styling for the widget and layout. · `frontend/src/app.css`
- [Vite build](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/frontend/vite.config.js): bundler · Frontend build and dev server configuration. · `frontend/vite.config.js`

### Backend

Express API that validates requests, orchestrates LLM calls, and persists conversations.

- [API server](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/index.ts): express entry · Bootstraps the TypeScript Express server. · `backend/src/index.ts`
- [Chat controller](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/controllers/chatController.ts): request handler · Handles message submission and orchestrates reply generation. · `backend/src/controllers/chatController.ts`
- [History controller](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/controllers/historyController.ts): request handler · Serves chronological conversation history for session restore. · `backend/src/controllers/historyController.ts`
- [Validation](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/middleware/validation.ts): middleware · Enforces request contracts before business logic executes. · `backend/src/middleware/validation.ts`
- [Error handler](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/middleware/errorHandler.ts): middleware · Normalizes failures into consistent API responses. · `backend/src/middleware/errorHandler.ts`
- [LLM service](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/services/llmService.ts): ai boundary · External model integration used to generate assistant replies. · `backend/src/services/llmService.ts`
- [Database service](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/services/databaseService.ts): persistence boundary · Reads and writes conversation and message records. · `backend/src/services/databaseService.ts`
- [Runtime config](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/src/config/index.ts): env config · Centralized server settings and API keys. · `backend/src/config/index.ts`
- [Prisma schema](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/prisma/schema.prisma): data model · Defines Conversation and Message persistence models. · `backend/prisma/schema.prisma`
- [Migrations](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/backend/prisma/migrations/20260623060511_init/migration.sql): schema history · Initial SQLite schema migration history. · `backend/prisma/migrations/20260623060511_init/migration.sql`

### Repo

Top-level repository metadata and semantic review notes.

- [README](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/README.md): docs · Repository overview and setup notes. · `README.md`
- [Review note](https://github.com/hugger-mugger/spur-ai-chat-assistant/blob/main/semantic-review/2025-01-sprint2-llm-context-integration.md): analysis · Semantic review artifact capturing the refactor context. · `semantic-review/2025-01-sprint2-llm-context-integration.md`

## Connections

- App shell → Chat widget: renders · The top-level app mounts the main chat widget.
- Chat widget → Message bubble: composes · The widget renders each message through the bubble component.
- Chat widget → API client: calls · Submits chat messages and loads history through the client boundary.
- Chat widget → Session cache: persists · Stores active session state and cached conversation data locally.
- App shell → App styles: styles · Global styles shape the client UI.
- Vite build → App shell: bundles · Vite builds the client application for static hosting.
- API server → Validation: guards · Requests are validated before entering controller logic.
- API server → Error handler: handles errors · API failures are normalized at the edge.
- API server → Chat controller: routes · Message submission flows through the chat controller.
- API server → History controller: routes · Conversation history requests flow through the history controller.
- Chat controller → LLM service: generates · Uses prior context to produce assistant replies.
- Chat controller → Database service: stores · Persists both user and assistant messages.
- History controller → Database service: reads · Fetches ordered message history for a conversation.
- Database service → Prisma schema: maps to · Database access is structured by the Prisma models.
- Database service → Migrations: evolves via · Schema changes are captured in migration history.
- Runtime config → API server: configures · Server startup and runtime behavior are environment-driven.
- Runtime config → LLM service: configures · LLM access depends on configured API keys and runtime settings.
- API client → API server: requests · Frontend network calls target the Express API.
