How cookieshop02/webot works
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 Agent Engine · auth.py Auth Routes · chat.py Chat Routes · Frontend.py Chat UI
Components 16
Frontend
User-facing chat UI and thread workspace
- Chat UI · Interactive chat interface with thread actions and streaming output
Frontend.py - Frontend Service · Containerized frontend runtime
Dockerfile.Frontend
Backend API
HTTP surface for auth and chat operations
- API App · Bootstraps the backend service and registers routes
backend/main.py - Auth Routes · Registration, login, and protected access endpoints
backend/routes/auth.py - Chat Routes · Conversation, thread, and message endpoints
backend/routes/chat.py - JWT · Token creation and verification
backend/auth/jwt.py - Auth Dep · Dependency helpers that resolve the current user
backend/auth/dependencies.py - Backend Service · Containerized backend runtime
backend/Dockerfile
Conversation Engine
LLM orchestration and durable thread state
- Agent Engine · System prompt, context trimming, LLM invocation, and token tracking
Backend.py - Thread Store · Persistent checkpointed conversation history keyed by thread_id
- Groq LLM · Hosted chat model used for assistant generation
- Thread State · Thread-scoped memory and metadata used to resume chats
- Stream Reply · Streaming assistant output returned to the UI
- Token Log · Per-turn token accounting and metadata reporting
Contracts
Typed request and response shapes
- Auth Schema · Validation models for auth requests and responses
backend/schemas/auth.py - Chat Schema · Validation models for chat and thread payloads
backend/schemas/chat.py
Connections 18
- 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