How bhagwatjadhav94/genie works
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: App.jsx SPA · chat.controller.js Chat domain · env.js Runtime config · auth.routes.js API routes
Components 18
Frontend
React/Vite single-page app and UI state
- SPA · Client application shell and route composition
frontend/src/App.jsx - Auth screens · Login and signup pages plus access guards
frontend/src/pages/Login.jsx - Chat UI · Chat page and message composition components
frontend/src/pages/ChatPage.jsx - Admin panel · Admin-facing upload and management surface
frontend/src/pages/AdminPanel.jsx - State hooks · Client-side auth and chat state management
frontend/src/hooks/useAuth.jsx - Route guards · Protected and admin-only route wrappers
frontend/src/components/auth/ProtectedRoute.jsx
Backend
Express API, AI orchestration, and ingestion pipeline
- Server entry · Process startup, app wiring, and environment loading
backend/src/index.js - API routes · Domain routing for auth, upload, and chat
backend/src/routes/auth.routes.js - Auth domain · Login/signup, JWT verification, and user persistence
backend/src/controllers/auth.controller.js - Ingestion domain · Admin upload, parsing, chunking, and embedding flow
backend/src/controllers/upload.controller.js - Chat domain · Question answering, retrieval, prompt assembly, and model calls
backend/src/controllers/chat.controller.js - Cross-cutting middleware · Auth, upload constraints, and rate limiting
backend/src/middleware/auth.middleware.js - Runtime config · Environment, prompt, DB, and Redis configuration
backend/src/config/env.js - Cache layer · Operational cache and Redis-backed support state
backend/src/services/cache.service.js
External services
Datastores and AI providers used by the backend
- MongoDB · Persistent user and auth metadata store
- Redis · Low-latency cache and operational state
- Pinecone · Semantic document embeddings and retrieval index
- LLM providers · External model APIs used for embeddings and answers
Connections 25
- 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