How techwithburhan/agent-pilot works
1. What this repo is
- This is a full-stack offline AI chat system called Ollama Agent.
- The core runtime is a React SPA talking to a Node/Express API, which in turn talks to MongoDB for persistence and Ollama for local LLM inference.
- The repo also includes Docker, Docker Compose, Kubernetes/KIND manifests, and a separate Terraform example for AWS infrastructure.
2. Main application boundary
- The product is split into two runtime tiers:
- Frontend: user-facing chat UI, login/signup, auth state, chat interactions.
- Backend: authentication, chat persistence, SSE streaming, and model access orchestration.
- The backend is the only component that talks directly to MongoDB and Ollama; the frontend never does.
3. Frontend subsystem
- frontend/src/App.js defines the app shell and route protection.
- frontend/src/context/AuthContext.js holds global auth state and likely stores the JWT client-side.
- Pages are separated by responsibility:
- Login.js and Signup.js for authentication flows.
- Chat.js for the main chat experience, including streaming responses, voice features, and file attachment handling.
- The frontend is built as a static app and served through Nginx in the container image.
4. Backend subsystem
- backend/server.js is the Express entry point and MongoDB bootstrap.
- backend/routes/auth.js handles signup/login/me, while backend/routes/chat.js handles message streaming and chat CRUD.
- backend/middleware/auth.js is the JWT guard used to protect chat endpoints.
- backend/models/User.js and backend/models/Chat.js define the persistence model in MongoDB via Mongoose.
5. Primary data flow: auth
- User registers or logs in from the frontend.
- The backend validates credentials, hashes passwords with bcrypt in the User model, and returns a JWT.
- The frontend stores the token and sends it on protected requests as a Bearer token.
- The auth middleware verifies the token and derives the user identity for chat operations.
6. Primary data flow: chat generation
- The user sends a message from Chat.js to POST /api/chat/message.
- The backend authenticates the request, persists or updates chat state in MongoDB, then forwards the prompt to Ollama.
- Response generation is streamed back to the browser using Server-Sent Events (SSE), which matters because token-by-token delivery is part of the UX.
- The frontend consumes the stream incrementally and updates the conversation view in real time.
7. Persistence boundary
- MongoDB stores two main collections: users and chats.
- mongo-init.js initializes those collections for Docker Compose.
- In Kubernetes, MongoDB is deployed as a StatefulSet with a PVC, which reflects that chat history is durable state and must survive restarts.
8. AI/runtime boundary
- Ollama is treated as an internal inference service, not an external SaaS dependency.
- The backend calls Ollama over its REST API using the configured model name.
- The repo emphasizes keeping Ollama private and local; in Compose it may be reached via host.docker.internal, while in Kubernetes it is a cluster service.
- The Ollama deployment includes persistent storage so downloaded model weights survive pod restarts.
9. Containerization layer
- Both frontend and backend have Dockerfiles, with the frontend using a build-then-serve pattern and the backend using a Node runtime image.
- docker-compose.yml wires together three services: MongoDB, backend, and frontend.
- This is the simplest complete runtime boundary in the repo: app code is containerized, but Ollama remains host-based in Compose.
10. Kubernetes deployment model
- The k8s/ directory defines a production-style cluster layout:
- Namespace for isolation
- ConfigMaps/Secrets for configuration separation
- Deployments for frontend/backend
- StatefulSet for MongoDB
- PVCs for MongoDB and Ollama data
- Ingress as the single HTTP entry point
- HPAs for frontend/backend scaling
- Backend and frontend are exposed internally via ClusterIP services; Ingress routes traffic by path to the correct service.
- There is also a NodePort for Ollama, likely for debugging or direct access in KIND.
11. Operational dependencies in Kubernetes
- The backend deployment depends on MongoDB being reachable before startup; the manifests likely use an initContainer or readiness gating for that.
- The Ollama deployment likely has an initContainer to pre-pull a model, which affects startup time and cluster readiness.
- The Ingress is intentionally applied last because it depends on all services already existing.
12. Infrastructure as code
- terraform-backend/ and terraform/ are a separate AWS example, not part of the app runtime itself.
- The Terraform setup demonstrates remote state in S3 with DynamoDB locking, then provisions EC2 instances using for_each.
- This is infrastructure around the project, not an application subsystem, but it is part of the repo’s deployment architecture story.
13. Repo structure implication
- There are two Kubernetes trees: k8s/ and ollama-agent-k8s/.
- They appear to be parallel deployment variants or a duplicated/older packaging of the same stack, with the same major components: frontend, backend, MongoDB, Ollama, cluster config.
- For an architecture diagram, treat them as alternate deployment manifests rather than separate application systems.
14. Important external boundaries
- The only materially important external systems are:
- MongoDB for durable application state
- Ollama for local LLM inference
- Kubernetes for orchestration
- Terraform/AWS for infrastructure provisioning
- The app is designed to avoid third-party AI APIs entirely; that offline/local constraint is a defining architectural property.
Main entry points: server.js Backend · App.js Frontend · mongo-init.js MongoDB · namespace.yaml K8s manifests
Components 18
Application
Core frontend and backend runtime for the offline chat product.
- Frontend · Browser client for login, signup, chat, and streamed response rendering.
frontend/src/App.js - Auth state · Client-side auth session state and token handling.
frontend/src/context/AuthContext.js - Login · User sign-in flow.
frontend/src/pages/Login.js - Signup · User registration flow.
frontend/src/pages/Signup.js - Chat · Main conversation UI with streaming, voice, and attachments.
frontend/src/pages/Chat.js - Backend · API entrypoint that handles auth, chat orchestration, persistence, and Ollama access.
backend/server.js - Auth routes · Signup, login, and current-user endpoints.
backend/routes/auth.js - Chat routes · Chat CRUD and SSE message streaming endpoints.
backend/routes/chat.js - JWT guard · Protects chat endpoints and derives user identity from bearer tokens.
backend/middleware/auth.js - User model · User persistence and password hashing behavior.
backend/models/User.js - Chat model · Stored chat threads and messages.
backend/models/Chat.js - MongoDB · Application database for users and chats.
mongo-init.js - Ollama · Local model inference service called by the backend.
k8s/ollama/deployment.yaml - Compose stack · Local container runtime wiring frontend, backend, and MongoDB together.
docker-compose.yml
Kubernetes
Cluster manifests and deployment variants for the application stack.
- K8s manifests · Primary Kubernetes deployment set for the app stack.
k8s/cluster/namespace.yaml - Alt K8s set · Alternate or duplicate Kubernetes packaging of the same runtime components.
ollama-agent-k8s/cluster/namespace.yaml
Infrastructure
Terraform-based AWS provisioning and backend state setup.
- TF backend · Remote Terraform state and locking backend on AWS.
terraform-backend/backend-infra.tf - TF infra · AWS infrastructure example for provisioning instances and related resources.
terraform/main.tf
Connections 29
- Frontend → Auth state: uses · App shell shares client auth state with pages.
- Frontend → Login: routes to · Unauthenticated users enter sign-in flow.
- Frontend → Signup: routes to · Unauthenticated users can register.
- Frontend → Chat: routes to · Protected route for the main chat experience.
- Chat → Backend: API calls · Sends auth and chat requests to the server.
- Login → Backend: auth request · Submits credentials to login endpoints.
- Signup → Backend: auth request · Submits new-account data to signup endpoints.
- Backend → Auth routes: exposes · Handles authentication endpoints.
- Backend → Chat routes: exposes · Handles chat and streaming endpoints.
- Chat routes → JWT guard: protects with · Requires JWT verification before chat access.
- Auth routes → User model: uses · Creates and verifies users through the model.
- Chat routes → Chat model: uses · Persists and loads chat threads.
- Backend → MongoDB: reads/writes · Stores users and chats in MongoDB.
- User model → MongoDB: persists · User records live in MongoDB.
- Chat model → MongoDB: persists · Chat history lives in MongoDB.
- Backend → Ollama: streams prompts · Forwards user prompts to local model inference.
- Compose stack → Backend: runs · Containerizes the API service.
- Compose stack → Frontend: runs · Containerizes the browser app served by Nginx.
- Compose stack → MongoDB: runs · Provides the database container.
- K8s manifests → Frontend: deploys · Kubernetes frontend deployment and service.
- K8s manifests → Backend: deploys · Kubernetes backend deployment and service.
- K8s manifests → MongoDB: deploys · Stateful MongoDB with persistent storage.
- K8s manifests → Ollama: deploys · Cluster-based Ollama inference service.
- Alt K8s set → Frontend: deploys · Alternate packaging for the frontend.
- Alt K8s set → Backend: deploys · Alternate packaging for the backend.
- Alt K8s set → MongoDB: deploys · Alternate packaging for MongoDB.
- Alt K8s set → Ollama: deploys · Alternate packaging for Ollama.
- TF backend → TF infra: supports · Remote state backend enables infrastructure provisioning.
- TF infra → MongoDB: provisions · AWS infrastructure is part of the broader deployment story, not the app runtime.