# techwithburhan/agent-pilot architecture

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

- Interactive diagram: https://gitdiagram.com/techwithburhan/agent-pilot
- Repository: https://github.com/techwithburhan/agent-pilot

## Overview

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: [`backend/server.js`](https://github.com/techwithburhan/agent-pilot/blob/main/backend/server.js) (Backend), [`frontend/src/App.js`](https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/App.js) (Frontend), [`mongo-init.js`](https://github.com/techwithburhan/agent-pilot/blob/main/mongo-init.js) (MongoDB), [`k8s/cluster/namespace.yaml`](https://github.com/techwithburhan/agent-pilot/blob/main/k8s/cluster/namespace.yaml) (K8s manifests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_frontend["Frontend<br/>React SPA<br/>[App.js]"]
  node_auth_context(("Auth state<br/>React context<br/>[AuthContext.js]"))
  node_login_page["Login<br/>auth page<br/>[Login.js]"]
  node_signup_page["Signup<br/>auth page<br/>[Signup.js]"]
  node_chat_page["Chat<br/>[Chat.js]"]
  node_backend["Backend<br/>Express API<br/>[server.js]"]
  node_auth_routes["Auth routes<br/>API routes<br/>[auth.js]"]
  node_chat_routes["Chat routes<br/>API routes<br/>[chat.js]"]
  node_auth_middleware["JWT guard<br/>middleware<br/>[auth.js]"]
  node_user_model[("User model<br/>Mongoose model<br/>[User.js]")]
  node_chat_model[("Chat model<br/>Mongoose model<br/>[Chat.js]")]
  node_mongodb[("MongoDB<br/>durable store<br/>[mongo-init.js]")]
  node_ollama{{"Ollama<br/>local LLM<br/>[deployment.yaml]"}}
  node_compose["Compose stack<br/>docker-compose<br/>[docker-compose.yml]"]
end

subgraph group_k8s["Kubernetes"]
  node_k8s_stack["K8s manifests<br/>deploy manifests<br/>[namespace.yaml]"]
  node_k8s_alt["Alt K8s set<br/>deploy manifests<br/>[namespace.yaml]"]
end

subgraph group_iac["Infrastructure"]
  node_terraform_backend["TF backend<br/>terraform state<br/>[backend-infra.tf]"]
  node_terraform_main["TF infra<br/>terraform modules<br/>[main.tf]"]
end

node_frontend -->|"uses"| node_auth_context
node_frontend -->|"routes to"| node_login_page
node_frontend -->|"routes to"| node_signup_page
node_frontend -->|"routes to"| node_chat_page
node_chat_page -->|"API calls"| node_backend
node_login_page -->|"auth request"| node_backend
node_signup_page -->|"auth request"| node_backend
node_backend -->|"exposes"| node_auth_routes
node_backend -->|"exposes"| node_chat_routes
node_chat_routes -->|"protects with"| node_auth_middleware
node_auth_routes -->|"uses"| node_user_model
node_chat_routes -->|"uses"| node_chat_model
node_backend -->|"reads/writes"| node_mongodb
node_user_model -->|"persists"| node_mongodb
node_chat_model -->|"persists"| node_mongodb
node_backend -->|"streams prompts"| node_ollama
node_compose -->|"runs"| node_backend
node_compose -->|"runs"| node_frontend
node_compose -->|"runs"| node_mongodb
node_k8s_stack -->|"deploys"| node_frontend
node_k8s_stack -->|"deploys"| node_backend
node_k8s_stack -->|"deploys"| node_mongodb
node_k8s_stack -->|"deploys"| node_ollama
node_k8s_alt -->|"deploys"| node_frontend
node_k8s_alt -->|"deploys"| node_backend
node_k8s_alt -->|"deploys"| node_mongodb
node_k8s_alt -->|"deploys"| node_ollama
node_terraform_backend -->|"supports"| node_terraform_main
node_terraform_main -.->|"provisions"| node_mongodb

click node_frontend "https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/App.js"
click node_auth_context "https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/context/AuthContext.js"
click node_login_page "https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/pages/Login.js"
click node_signup_page "https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/pages/Signup.js"
click node_chat_page "https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/pages/Chat.js"
click node_backend "https://github.com/techwithburhan/agent-pilot/blob/main/backend/server.js"
click node_auth_routes "https://github.com/techwithburhan/agent-pilot/blob/main/backend/routes/auth.js"
click node_chat_routes "https://github.com/techwithburhan/agent-pilot/blob/main/backend/routes/chat.js"
click node_auth_middleware "https://github.com/techwithburhan/agent-pilot/blob/main/backend/middleware/auth.js"
click node_user_model "https://github.com/techwithburhan/agent-pilot/blob/main/backend/models/User.js"
click node_chat_model "https://github.com/techwithburhan/agent-pilot/blob/main/backend/models/Chat.js"
click node_mongodb "https://github.com/techwithburhan/agent-pilot/blob/main/mongo-init.js"
click node_ollama "https://github.com/techwithburhan/agent-pilot/blob/main/k8s/ollama/deployment.yaml"
click node_compose "https://github.com/techwithburhan/agent-pilot/blob/main/docker-compose.yml"
click node_k8s_stack "https://github.com/techwithburhan/agent-pilot/blob/main/k8s/cluster/namespace.yaml"
click node_k8s_alt "https://github.com/techwithburhan/agent-pilot/blob/main/ollama-agent-k8s/cluster/namespace.yaml"
click node_terraform_backend "https://github.com/techwithburhan/agent-pilot/blob/main/terraform-backend/backend-infra.tf"
click node_terraform_main "https://github.com/techwithburhan/agent-pilot/blob/main/terraform/main.tf"

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,node_auth_context,node_login_page,node_signup_page,node_chat_page,node_backend,node_auth_routes,node_chat_routes,node_auth_middleware,node_user_model,node_chat_model,node_mongodb,node_ollama,node_compose toneBlue
class node_k8s_stack,node_k8s_alt toneAmber
class node_terraform_backend,node_terraform_main toneMint
```

## Components

### Application

Core frontend and backend runtime for the offline chat product.

- [Frontend](https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/App.js): React SPA · Browser client for login, signup, chat, and streamed response rendering. · `frontend/src/App.js`
- [Auth state](https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/context/AuthContext.js): React context · Client-side auth session state and token handling. · `frontend/src/context/AuthContext.js`
- [Login](https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/pages/Login.js): auth page · User sign-in flow. · `frontend/src/pages/Login.js`
- [Signup](https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/pages/Signup.js): auth page · User registration flow. · `frontend/src/pages/Signup.js`
- [Chat](https://github.com/techwithburhan/agent-pilot/blob/main/frontend/src/pages/Chat.js): chat UI · Main conversation UI with streaming, voice, and attachments. · `frontend/src/pages/Chat.js`
- [Backend](https://github.com/techwithburhan/agent-pilot/blob/main/backend/server.js): Express API · API entrypoint that handles auth, chat orchestration, persistence, and Ollama access. · `backend/server.js`
- [Auth routes](https://github.com/techwithburhan/agent-pilot/blob/main/backend/routes/auth.js): API routes · Signup, login, and current-user endpoints. · `backend/routes/auth.js`
- [Chat routes](https://github.com/techwithburhan/agent-pilot/blob/main/backend/routes/chat.js): API routes · Chat CRUD and SSE message streaming endpoints. · `backend/routes/chat.js`
- [JWT guard](https://github.com/techwithburhan/agent-pilot/blob/main/backend/middleware/auth.js): middleware · Protects chat endpoints and derives user identity from bearer tokens. · `backend/middleware/auth.js`
- [User model](https://github.com/techwithburhan/agent-pilot/blob/main/backend/models/User.js): Mongoose model · User persistence and password hashing behavior. · `backend/models/User.js`
- [Chat model](https://github.com/techwithburhan/agent-pilot/blob/main/backend/models/Chat.js): Mongoose model · Stored chat threads and messages. · `backend/models/Chat.js`
- [MongoDB](https://github.com/techwithburhan/agent-pilot/blob/main/mongo-init.js): durable store · Application database for users and chats. · `mongo-init.js`
- [Ollama](https://github.com/techwithburhan/agent-pilot/blob/main/k8s/ollama/deployment.yaml): local LLM · Local model inference service called by the backend. · `k8s/ollama/deployment.yaml`
- [Compose stack](https://github.com/techwithburhan/agent-pilot/blob/main/docker-compose.yml): docker-compose · Local container runtime wiring frontend, backend, and MongoDB together. · `docker-compose.yml`

### Kubernetes

Cluster manifests and deployment variants for the application stack.

- [K8s manifests](https://github.com/techwithburhan/agent-pilot/blob/main/k8s/cluster/namespace.yaml): deploy manifests · Primary Kubernetes deployment set for the app stack. · `k8s/cluster/namespace.yaml`
- [Alt K8s set](https://github.com/techwithburhan/agent-pilot/blob/main/ollama-agent-k8s/cluster/namespace.yaml): deploy manifests · 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](https://github.com/techwithburhan/agent-pilot/blob/main/terraform-backend/backend-infra.tf): terraform state · Remote Terraform state and locking backend on AWS. · `terraform-backend/backend-infra.tf`
- [TF infra](https://github.com/techwithburhan/agent-pilot/blob/main/terraform/main.tf): terraform modules · AWS infrastructure example for provisioning instances and related resources. · `terraform/main.tf`

## Connections

- 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.