# cookieshop02/webot architecture

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

- Interactive diagram: https://gitdiagram.com/cookieshop02/webot
- Repository: https://github.com/cookieshop02/webot

## Overview

1. **High-level shape**
   - This repo is a **two-service Python application**: a **frontend** process and a **backend API** process.
   - The frontend is represented by `Frontend.py` at the repo root.
   - The backend lives under `backend/` and is structured as a FastAPI-style API with route modules, auth helpers, and request/response schemas.

2. **Frontend boundary**
   - `Frontend.py` is the user-facing chat interface.
   - Its job is to manage chat interaction, current thread selection, and rendering of streamed assistant output.
   - Based on the README, it also handles sidebar actions like creating threads, renaming/deleting threads, exporting chat, and showing token/thread metadata.

3. **Backend API boundary**
   - `backend/main.py` is the application entrypoint for the API service.
   - `backend/routes/auth.py` and `backend/routes/chat.py` split the API into two domains:
     - **auth**: registration/login and JWT-protected access
     - **chat**: conversation/thread/message operations
   - This separation suggests the frontend talks to the backend over HTTP rather than directly to the LLM runtime.

4. **Authentication subsystem**
   - `backend/auth/jwt.py` is responsible for JWT creation and verification.
   - `backend/auth/dependencies.py` likely provides request dependencies that protect routes and resolve the current user from a token.
   - `backend/schemas/auth.py` defines the input/output contracts for auth endpoints, keeping request validation and API shapes centralized.

5. **Chat/domain schema layer**
   - `backend/schemas/chat.py` defines the structured payloads for chat-related API calls.
   - This is the boundary between the UI/API layer and the internal conversation model, so it is important for diagramming request flow and validation points.

6. **Conversation engine**
   - The root-level `Backend.py` is the core conversational engine.
   - The README describes it as the LangGraph-based state machine that:
     - injects the system prompt
     - trims context
     - invokes the Groq LLM
     - logs token usage
     - returns assistant responses
   - In the architecture, this is the main “LLM orchestration” layer behind the chat routes.

7. **State and persistence**
   - Conversation memory is persistent and thread-scoped.
   - The README describes checkpointing by `thread_id`, with history surviving refreshes/restarts.
   - The exact persistence backend may have evolved, but architecturally this is a **durable checkpoint store** behind the graph, not just in-memory session state.

8. **External AI dependency**
   - The LLM is Groq, using a chat model such as `llama-3.1-8b-instant` per the README.
   - This is the only major external AI service in the stack and sits behind the backend engine, not directly in the frontend.

9. **Data flow through the system**
   - The main request path is:
     - user message in the frontend
     - API call to backend chat route
     - backend auth check if needed
     - backend hands the message to the LangGraph engine
     - engine reads/writes thread state in the checkpoint store
     - engine calls Groq
     - response streams or returns to frontend
   - This is the core path to show on an architecture diagram.

10. **Threading model**
   - Conversation identity is thread-based, using a stable `thread_id`.
   - The frontend manages thread selection in UI state, while the backend uses that identifier to load the right conversation history.
   - This makes “thread” the main unit of persistence and UX continuity.

11. **Deployment and containerization**
   - `backend/Dockerfile`, `Dockerfile.Frontend`, and `docker-compose.yml` indicate the app is designed to run as separate containers.
   - That means the architecture should show at least two deployable services: frontend container and backend container, with networking between them.

12. **Project organization**
   - The `backend/` package is intentionally layered:
     - `main.py` for app bootstrapping
     - `routes/` for transport/API endpoints
     - `auth/` for security concerns
     - `schemas/` for typed contracts
   - This is a clean separation between transport, business logic, and auth/payload validation.

13. **What to emphasize in a diagram**
   - Show the frontend as the interactive client.
   - Show the backend as the API and orchestration layer.
   - Show auth as a cross-cutting control point on protected routes.
   - Show the LangGraph engine and LLM as the core compute path.
   - Show persistent checkpoint storage as the state boundary that makes threads durable.

Main entry points: [`Backend.py`](https://github.com/cookieshop02/webot/blob/main/Backend.py) (Agent Engine), [`backend/routes/auth.py`](https://github.com/cookieshop02/webot/blob/main/backend/routes/auth.py) (Auth Routes), [`backend/routes/chat.py`](https://github.com/cookieshop02/webot/blob/main/backend/routes/chat.py) (Chat Routes), [`Frontend.py`](https://github.com/cookieshop02/webot/blob/main/Frontend.py) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_ui["Chat UI<br/>ui client<br/>[Frontend.py]"]
  node_frontend_pkg["Frontend Service<br/>deployable service"]
end

subgraph group_api["Backend API"]
  node_backend_main["API App<br/>api entrypoint<br/>[main.py]"]
  node_auth_routes["Auth Routes<br/>http routes<br/>[auth.py]"]
  node_chat_routes["Chat Routes<br/>http routes<br/>[chat.py]"]
  node_jwt_auth{{"JWT<br/>security helper<br/>[jwt.py]"}}
  node_auth_deps{{"Auth Dep<br/>request guard<br/>[dependencies.py]"}}
  node_backend_pkg["Backend Service<br/>deployable service"]
end

subgraph group_engine["Conversation Engine"]
  node_engine_core["Agent Engine<br/>langgraph core<br/>[Backend.py]"]
  node_checkpoint_store[("Thread Store<br/>durable state")]
  node_groq_llm(("Groq LLM<br/>external model"))
  node_thread_state["Thread State<br/>conversation state"]
  node_streaming_output["Stream Reply<br/>response stream"]
  node_token_usage["Token Log<br/>telemetry"]
end

subgraph group_contracts["Contracts"]
  node_auth_schema["Auth Schema<br/>contract<br/>[auth.py]"]
  node_chat_schema["Chat Schema<br/>contract<br/>[chat.py]"]
end

node_frontend_ui -->|"calls API"| node_backend_main
node_backend_main -->|"mounts"| node_auth_routes
node_backend_main -->|"mounts"| node_chat_routes
node_auth_routes -->|"validates"| node_auth_schema
node_chat_routes -->|"validates"| node_chat_schema
node_auth_routes -->|"issues tokens"| node_jwt_auth
node_auth_routes -->|"protects"| node_auth_deps
node_chat_routes -->|"guards"| node_auth_deps
node_chat_routes -->|"dispatches"| node_engine_core
node_engine_core -->|"loads state"| node_thread_state
node_engine_core -->|"persists"| node_checkpoint_store
node_engine_core -->|"invokes"| node_groq_llm
node_engine_core -->|"records"| node_token_usage
node_engine_core -->|"returns"| node_streaming_output
node_streaming_output -->|"renders"| node_frontend_ui
node_backend_pkg -->|"runs"| node_backend_main
node_frontend_pkg -->|"runs"| node_frontend_ui
node_frontend_ui -->|"selects thread"| node_thread_state

click node_frontend_ui "https://github.com/cookieshop02/webot/blob/main/Frontend.py"
click node_backend_main "https://github.com/cookieshop02/webot/blob/main/backend/main.py"
click node_auth_routes "https://github.com/cookieshop02/webot/blob/main/backend/routes/auth.py"
click node_chat_routes "https://github.com/cookieshop02/webot/blob/main/backend/routes/chat.py"
click node_jwt_auth "https://github.com/cookieshop02/webot/blob/main/backend/auth/jwt.py"
click node_auth_deps "https://github.com/cookieshop02/webot/blob/main/backend/auth/dependencies.py"
click node_auth_schema "https://github.com/cookieshop02/webot/blob/main/backend/schemas/auth.py"
click node_chat_schema "https://github.com/cookieshop02/webot/blob/main/backend/schemas/chat.py"
click node_engine_core "https://github.com/cookieshop02/webot/blob/main/Backend.py"
click node_backend_pkg "https://github.com/cookieshop02/webot/tree/main/backend/Dockerfile"
click node_frontend_pkg "https://github.com/cookieshop02/webot/blob/main/Dockerfile.Frontend"

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_frontend_ui,node_frontend_pkg toneBlue
class node_backend_main,node_auth_routes,node_chat_routes,node_jwt_auth,node_auth_deps,node_backend_pkg toneAmber
class node_engine_core,node_checkpoint_store,node_groq_llm,node_thread_state,node_streaming_output,node_token_usage toneMint
class node_auth_schema,node_chat_schema toneRose
```

## Components

### Frontend

User-facing chat UI and thread workspace

- [Chat UI](https://github.com/cookieshop02/webot/blob/main/Frontend.py): ui client · Interactive chat interface with thread actions and streaming output · `Frontend.py`
- [Frontend Service](https://github.com/cookieshop02/webot/blob/main/Dockerfile.Frontend): deployable service · Containerized frontend runtime · `Dockerfile.Frontend`

### Backend API

HTTP surface for auth and chat operations

- [API App](https://github.com/cookieshop02/webot/blob/main/backend/main.py): api entrypoint · Bootstraps the backend service and registers routes · `backend/main.py`
- [Auth Routes](https://github.com/cookieshop02/webot/blob/main/backend/routes/auth.py): http routes · Registration, login, and protected access endpoints · `backend/routes/auth.py`
- [Chat Routes](https://github.com/cookieshop02/webot/blob/main/backend/routes/chat.py): http routes · Conversation, thread, and message endpoints · `backend/routes/chat.py`
- [JWT](https://github.com/cookieshop02/webot/blob/main/backend/auth/jwt.py): security helper · Token creation and verification · `backend/auth/jwt.py`
- [Auth Dep](https://github.com/cookieshop02/webot/blob/main/backend/auth/dependencies.py): request guard · Dependency helpers that resolve the current user · `backend/auth/dependencies.py`
- [Backend Service](https://github.com/cookieshop02/webot/tree/main/backend/Dockerfile): deployable service · Containerized backend runtime · `backend/Dockerfile`

### Conversation Engine

LLM orchestration and durable thread state

- [Agent Engine](https://github.com/cookieshop02/webot/blob/main/Backend.py): langgraph core · System prompt, context trimming, LLM invocation, and token tracking · `Backend.py`
- **Thread Store**: durable state · Persistent checkpointed conversation history keyed by thread_id
- **Groq LLM**: external model · Hosted chat model used for assistant generation
- **Thread State**: conversation state · Thread-scoped memory and metadata used to resume chats
- **Stream Reply**: response stream · Streaming assistant output returned to the UI
- **Token Log**: telemetry · Per-turn token accounting and metadata reporting

### Contracts

Typed request and response shapes

- [Auth Schema](https://github.com/cookieshop02/webot/blob/main/backend/schemas/auth.py): contract · Validation models for auth requests and responses · `backend/schemas/auth.py`
- [Chat Schema](https://github.com/cookieshop02/webot/blob/main/backend/schemas/chat.py): contract · Validation models for chat and thread payloads · `backend/schemas/chat.py`

## Connections

- Chat UI → API App: calls API · Frontend sends chat and thread operations to the backend service
- API App → Auth Routes: mounts · Backend app registers auth endpoints
- API App → Chat Routes: mounts · Backend app registers chat endpoints
- Auth Routes → Auth Schema: validates · Auth requests and responses are typed by schema models
- Chat Routes → Chat Schema: validates · Chat requests and responses are typed by schema models
- Auth Routes → JWT: issues tokens · Login and registration rely on JWT creation and verification
- Auth Routes → Auth Dep: protects · Protected auth flows use dependency-based user resolution
- Chat Routes → Auth Dep: guards · Chat operations are associated with authenticated users when required
- Chat Routes → Agent Engine: dispatches · Chat payloads are handed to the conversation engine
- Agent Engine → Thread State: loads state · Engine resumes the current thread's conversation context
- Agent Engine → Thread Store: persists · Thread checkpoints are written for durable continuity
- Agent Engine → Groq LLM: invokes · Engine calls the external LLM for generation
- Agent Engine → Token Log: records · Engine tracks token and usage metadata
- Agent Engine → Stream Reply: returns · Assistant responses are streamed or emitted back to the caller
- Stream Reply → Chat UI: renders · Frontend displays streamed assistant tokens and final replies
- Backend Service → API App: runs · Backend container starts the API application
- Frontend Service → Chat UI: runs · Frontend container serves the chat interface
- Chat UI → Thread State: selects thread · UI keeps the active thread as the main conversation context
