How hugger-mugger/spur-ai-chat-assistant works
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: index.ts API server · ChatWidget.svelte Chat widget · databaseService.ts Database service · chatController.ts Chat controller
Components 19
Frontend
Svelte/Vite client that renders the chat widget and restores conversation state locally.
- App shell · Top-level Svelte entry that mounts the chat experience.
frontend/src/App.svelte - Chat widget · Main chat interface and local session restoration logic.
frontend/src/lib/ChatWidget.svelte - Message bubble · Renders individual user and assistant messages.
frontend/src/lib/MessageBubble.svelte - API client · Frontend wrapper for backend chat and history requests.
frontend/src/lib/api.ts - Session cache · Persists sessionId and cached conversation state across reloads.
- App styles · Global styling for the widget and layout.
frontend/src/app.css - Vite build · Frontend build and dev server configuration.
frontend/vite.config.js
Backend
Express API that validates requests, orchestrates LLM calls, and persists conversations.
- API server · Bootstraps the TypeScript Express server.
backend/src/index.ts - Chat controller · Handles message submission and orchestrates reply generation.
backend/src/controllers/chatController.ts - History controller · Serves chronological conversation history for session restore.
backend/src/controllers/historyController.ts - Validation · Enforces request contracts before business logic executes.
backend/src/middleware/validation.ts - Error handler · Normalizes failures into consistent API responses.
backend/src/middleware/errorHandler.ts - LLM service · External model integration used to generate assistant replies.
backend/src/services/llmService.ts - Database service · Reads and writes conversation and message records.
backend/src/services/databaseService.ts - Runtime config · Centralized server settings and API keys.
backend/src/config/index.ts - Prisma schema · Defines Conversation and Message persistence models.
backend/prisma/schema.prisma - Migrations · Initial SQLite schema migration history.
backend/prisma/migrations/20260623060511_init/migration.sql
Repo
Top-level repository metadata and semantic review notes.
- README · Repository overview and setup notes.
README.md - Review note · Semantic review artifact capturing the refactor context.
semantic-review/2025-01-sprint2-llm-context-integration.md
Connections 18
- 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.