# bhagwatjadhav94/genie architecture

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

- Interactive diagram: https://gitdiagram.com/bhagwatjadhav94/genie
- Repository: https://github.com/bhagwatjadhav94/genie

## Overview

1. **System boundary**
   - This is a two-tier full-stack app: a React/Vite frontend talks to an Express/Node.js backend over HTTP.
   - The backend is the architectural center: it handles authentication, document ingestion, AI chat, and all integrations with external services.

2. **User-facing frontend**
   - The frontend is a single-page app organized around pages and feature components: login/signup, chat, and an admin panel.
   - `useAuth` and `useChat` are the main state/data hooks, while `token.utils` suggests JWT handling on the client.
   - `ProtectedRoute` and `AdminRoute` enforce access boundaries in the UI, mirroring backend authorization.

3. **Backend entry and composition**
   - `src/index.js` is the startup point, `app.js` likely wires Express middleware and routes, and `config/env.js` loads runtime settings.
   - Route modules split the API into three domains: auth, upload, and chat.
   - This separation is important for diagramming because ingestion and chat are distinct workflows even though they share authentication and storage.

4. **Authentication and role model**
   - The backend uses JWT-based auth with a `user.model.js` persisted in MongoDB Atlas.
   - `auth.middleware.js` protects private endpoints, and the frontend route guards match the same access model.
   - The README and file structure indicate role-based access control for at least Admin vs User.

5. **Document ingestion pipeline**
   - Admin-only upload flow starts in `upload.controller.js` and is constrained by `upload.middleware.js`.
   - Uploaded policy files are parsed via `pdfParser.js`, then split into chunks via `chunker.js`.
   - Those chunks are sent into the embedding/vector pipeline, so ingestion is a multi-step transform rather than a simple file save.

6. **Vector search and knowledge retrieval**
   - `pinecone.service.js` is the vector storage/retrieval boundary, so the document knowledge base lives outside MongoDB.
   - The backend stores document embeddings in Pinecone and later queries Pinecone for semantically relevant context during chat.
   - This means the system has two persistence layers with different purposes: MongoDB for users/auth metadata and Pinecone for semantic document retrieval.

7. **Chat generation path**
   - `chat.controller.js` and `chat.service.js` implement the question-answer flow.
   - The service layer likely assembles retrieved context, builds a prompt, and calls an LLM provider through `gemini.service.js` and/or `openai.service.js`.
   - `promptBuilder.service.js` and `prompt.config.js` indicate the answer prompt is centralized and configurable, which is key to the AI behavior boundary.

8. **Caching and rate control**
   - `cache.service.js` and `redis.js` show Redis is used as an operational cache or session/state accelerator, not as the primary database.
   - `rateLimiter.middleware.js` adds an API guardrail, likely especially relevant for AI endpoints to control cost and abuse.
   - These are cross-cutting concerns that sit in front of the controller/service layer.

9. **External services and runtime dependencies**
   - The main external dependencies are MongoDB Atlas, Pinecone, Google Gemini, and OpenAI.
   - The README emphasizes Gemini for embeddings/chat, while the codebase also includes OpenAI support, so the architecture should treat the LLM provider as a pluggable integration.
   - Environment variables drive all of these connections, so deployment is config-heavy and secrets-based.

10. **Frontend-backend contract**
   - The frontend points to a single API base URL via `src/config/api.js`, and the backend exposes a small, domain-based API surface.
   - Auth tokens flow from login/signup to protected requests, and the chat UI consumes the chat endpoint for responses.
   - The existence of frontend HTML tests for streaming chat suggests the chat API may support incremental/streamed output, which matters for UI architecture.

11. **Operational concerns and validation**
   - The repo contains YAML load/test definitions under `backend/tests`, indicating API and load validation are part of the backend workflow.
   - Frontend test pages in `backend/tests/frontendtest` imply manual or browser-based verification of the chat interaction path.
   - There is no separate worker service in the tree; ingestion, retrieval, and generation all appear to run inside the main backend process.

12. **How to diagram the system**
   - Draw the frontend as the presentation layer with auth and chat screens.
   - Draw the backend as four internal blocks: auth, upload/ingestion, retrieval/chat, and shared middleware/config.
   - Show MongoDB as user/auth persistence, Redis as cache/rate-support, Pinecone as vector index, and Gemini/OpenAI as external AI providers.
   - The key data flow is: admin upload → parse/chunk/embed → Pinecone; user question → auth check → vector retrieval → prompt build → LLM response → frontend display.

Main entry points: [`frontend/src/App.jsx`](https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/App.jsx) (SPA), [`backend/src/controllers/chat.controller.js`](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/controllers/chat.controller.js) (Chat domain), [`backend/src/config/env.js`](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/config/env.js) (Runtime config), [`backend/src/routes/auth.routes.js`](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/routes/auth.routes.js) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA<br/>React/Vite app<br/>[App.jsx]"]
  node_frontend_auth_pages["Auth screens<br/>login/signup UI<br/>[Login.jsx]"]
  node_frontend_chat_pages["Chat UI<br/>chat experience<br/>[ChatPage.jsx]"]
  node_frontend_admin_page["Admin panel<br/>admin UI<br/>[AdminPanel.jsx]"]
  node_frontend_state_hooks["State hooks<br/>auth/chat hooks<br/>[useAuth.jsx]"]
  node_frontend_route_guards["Route guards<br/>access control<br/>[ProtectedRoute.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_entry["Server entry<br/>Express bootstrap<br/>[index.js]"]
  node_backend_routes["API routes<br/>route layer<br/>[auth.routes.js]"]
  node_backend_auth["Auth domain<br/>JWT auth<br/>[auth.controller.js]"]
  node_backend_upload["Ingestion domain<br/>document pipeline"]
  node_backend_chat["Chat domain<br/>QA orchestration<br/>[chat.controller.js]"]
  node_backend_middleware["Cross-cutting middleware<br/>guards/limits<br/>[auth.middleware.js]"]
  node_backend_config["Runtime config<br/>env/settings<br/>[env.js]"]
  node_backend_cache[("Cache layer<br/>Redis cache<br/>[cache.service.js]")]
end

subgraph group_external["External services"]
  node_mongo_db[("MongoDB<br/>user store")]
  node_redis_store[("Redis<br/>cache store")]
  node_pinecone_index[("Pinecone<br/>vector index")]
  node_llm_providers(("LLM providers<br/>Gemini/OpenAI"))
end

node_frontend_app -->|"renders"| node_frontend_auth_pages
node_frontend_app -->|"renders"| node_frontend_chat_pages
node_frontend_app -->|"renders"| node_frontend_admin_page
node_frontend_app -->|"uses"| node_frontend_state_hooks
node_frontend_app -->|"wraps"| node_frontend_route_guards
node_frontend_app -->|"HTTP API"| node_backend_routes
node_backend_entry -->|"wires"| node_backend_routes
node_backend_entry -->|"loads"| node_backend_config
node_backend_routes -->|"auth"| node_backend_auth
node_backend_routes -->|"upload"| node_backend_upload
node_backend_routes -->|"chat"| node_backend_chat
node_backend_auth -->|"protected by"| node_backend_middleware
node_backend_upload -->|"protected by"| node_backend_middleware
node_backend_chat -->|"protected by"| node_backend_middleware
node_backend_auth -->|"persists users"| node_mongo_db
node_backend_upload -->|"embeds"| node_pinecone_index
node_backend_chat -->|"retrieves context"| node_pinecone_index
node_backend_chat -->|"generates answers"| node_llm_providers
node_backend_upload -->|"creates embeddings"| node_llm_providers
node_backend_chat -->|"uses"| node_backend_cache
node_backend_cache -->|"backed by"| node_redis_store
node_backend_config -->|"configures"| node_mongo_db
node_backend_config -->|"configures"| node_redis_store
node_backend_config -->|"configures"| node_pinecone_index
node_backend_config -->|"configures"| node_llm_providers

click node_frontend_app "https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/App.jsx"
click node_frontend_auth_pages "https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/pages/Login.jsx"
click node_frontend_chat_pages "https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/pages/ChatPage.jsx"
click node_frontend_admin_page "https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/pages/AdminPanel.jsx"
click node_frontend_state_hooks "https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/hooks/useAuth.jsx"
click node_frontend_route_guards "https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/components/auth/ProtectedRoute.jsx"
click node_backend_entry "https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/index.js"
click node_backend_routes "https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/routes/auth.routes.js"
click node_backend_auth "https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/controllers/auth.controller.js"
click node_backend_upload "https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/controllers/upload.controller.js"
click node_backend_chat "https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/controllers/chat.controller.js"
click node_backend_middleware "https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/middleware/auth.middleware.js"
click node_backend_config "https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/config/env.js"
click node_backend_cache "https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/services/cache.service.js"

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_app,node_frontend_auth_pages,node_frontend_chat_pages,node_frontend_admin_page,node_frontend_state_hooks,node_frontend_route_guards toneBlue
class node_backend_entry,node_backend_routes,node_backend_auth,node_backend_upload,node_backend_chat,node_backend_middleware,node_backend_config,node_backend_cache toneAmber
class node_mongo_db,node_redis_store,node_pinecone_index,node_llm_providers toneMint
```

## Components

### Frontend

React/Vite single-page app and UI state

- [SPA](https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/App.jsx): React/Vite app · Client application shell and route composition · `frontend/src/App.jsx`
- [Auth screens](https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/pages/Login.jsx): login/signup UI · Login and signup pages plus access guards · `frontend/src/pages/Login.jsx`
- [Chat UI](https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/pages/ChatPage.jsx): chat experience · Chat page and message composition components · `frontend/src/pages/ChatPage.jsx`
- [Admin panel](https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/pages/AdminPanel.jsx): admin UI · Admin-facing upload and management surface · `frontend/src/pages/AdminPanel.jsx`
- [State hooks](https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/hooks/useAuth.jsx): auth/chat hooks · Client-side auth and chat state management · `frontend/src/hooks/useAuth.jsx`
- [Route guards](https://github.com/bhagwatjadhav94/genie/blob/main/frontend/src/components/auth/ProtectedRoute.jsx): access control · Protected and admin-only route wrappers · `frontend/src/components/auth/ProtectedRoute.jsx`

### Backend

Express API, AI orchestration, and ingestion pipeline

- [Server entry](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/index.js): Express bootstrap · Process startup, app wiring, and environment loading · `backend/src/index.js`
- [API routes](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/routes/auth.routes.js): route layer · Domain routing for auth, upload, and chat · `backend/src/routes/auth.routes.js`
- [Auth domain](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/controllers/auth.controller.js): JWT auth · Login/signup, JWT verification, and user persistence · `backend/src/controllers/auth.controller.js`
- [Ingestion domain](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/controllers/upload.controller.js): document pipeline · Admin upload, parsing, chunking, and embedding flow · `backend/src/controllers/upload.controller.js`
- [Chat domain](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/controllers/chat.controller.js): QA orchestration · Question answering, retrieval, prompt assembly, and model calls · `backend/src/controllers/chat.controller.js`
- [Cross-cutting middleware](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/middleware/auth.middleware.js): guards/limits · Auth, upload constraints, and rate limiting · `backend/src/middleware/auth.middleware.js`
- [Runtime config](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/config/env.js): env/settings · Environment, prompt, DB, and Redis configuration · `backend/src/config/env.js`
- [Cache layer](https://github.com/bhagwatjadhav94/genie/blob/main/backend/src/services/cache.service.js): Redis cache · Operational cache and Redis-backed support state · `backend/src/services/cache.service.js`

### External services

Datastores and AI providers used by the backend

- **MongoDB**: user store · Persistent user and auth metadata store
- **Redis**: cache store · Low-latency cache and operational state
- **Pinecone**: vector index · Semantic document embeddings and retrieval index
- **LLM providers**: Gemini/OpenAI · External model APIs used for embeddings and answers

## Connections

- SPA → Auth screens: renders · SPA composes login and signup screens
- SPA → Chat UI: renders · SPA composes the main chat experience
- SPA → Admin panel: renders · SPA exposes admin workflow
- SPA → State hooks: uses · UI state and API orchestration
- SPA → Route guards: wraps · Client-side access boundaries
- SPA → API routes: HTTP API · Frontend calls backend domains through one API base URL
- Server entry → API routes: wires · Bootstraps the Express application and route modules
- Server entry → Runtime config: loads · Reads runtime configuration and secrets
- API routes → Auth domain: auth · Auth endpoints are routed to the auth controller
- API routes → Ingestion domain: upload · Upload endpoints are routed to ingestion logic
- API routes → Chat domain: chat · Chat endpoints are routed to QA orchestration
- Auth domain → Cross-cutting middleware: protected by · JWT middleware guards private auth-adjacent endpoints
- Ingestion domain → Cross-cutting middleware: protected by · Upload flow is restricted and rate-limited
- Chat domain → Cross-cutting middleware: protected by · Chat flow is authenticated and throttled
- Auth domain → MongoDB: persists users · User records and roles are stored in MongoDB
- Ingestion domain → Pinecone: embeds · Parsed chunks are stored as vector knowledge
- Chat domain → Pinecone: retrieves context · Semantic search fetches relevant document chunks
- Chat domain → LLM providers: generates answers · Prompted responses come from Gemini/OpenAI integrations
- Ingestion domain → LLM providers: creates embeddings · Document ingestion may call model APIs for vectorization
- Chat domain → Cache layer: uses · Chat flow can leverage cache for operational acceleration
- Cache layer → Redis: backed by · Redis is the physical cache store
- Runtime config → MongoDB: configures · Database connection settings are environment-driven
- Runtime config → Redis: configures · Redis connection settings are environment-driven
- Runtime config → Pinecone: configures · Vector index settings are environment-driven
- Runtime config → LLM providers: configures · Model API keys and provider selection are environment-driven
