How priyanshudwivedi9068-eng/academicai works
1. System shape
- This is a two-tier application: a React/Vite frontend and a Node.js/Express backend.
- The backend is the system of record for users, uploaded documents, and AI interactions; the frontend is a single-page app that consumes the backend API.
2. Frontend boundary
- The frontend lives under frontend/src and is organized into pages, layouts, components, and React contexts.
- Key contexts are AuthContext and ThemeContext, which indicate that authentication state and UI theme are managed client-side and shared across the app.
- ProtectedRoute and DashboardLayout suggest a gated dashboard area versus public entry pages like login/register/home.
3. Primary user-facing areas
- Public entry points: Home, Login, and Register.
- Authenticated workspace: Dashboard with feature pages for Overview, AIChat, FileManager, StudyRoom, CalendarView, Billing, and Settings.
- The architecture strongly implies that most product value happens inside the authenticated dashboard, not as isolated public pages.
4. Backend API structure
- The backend is a classic Express controller-route-service layout.
- routes/ maps HTTP endpoints to controllers/, and middleware/ handles cross-cutting concerns like auth protection.
- The main functional domains are:
- authController / authRoutes
- fileController / fileRoutes
- aiController / aiRoutes
- server.js is the entrypoint that wires the Express app together.
5. Data model boundary
- MongoDB is accessed through Mongoose models in backend/models.
- User holds identity/auth-related data.
- Document likely tracks uploaded files, parsing metadata, ownership, and possibly vector/index references.
- This makes MongoDB the durable application database, while the vector store is used for semantic retrieval rather than primary storage.
6. Document ingestion pipeline
- The upload flow is centered around fileController and likely uses multer for file intake.
- Supported document types in the README are PDF, DOCX, and TXT, which implies format-specific parsing before downstream processing.
- The ingestion pipeline converts raw files into normalized text, then persists metadata in MongoDB and sends content into the retrieval layer.
7. RAG and vector search subsystem
- services/ragService.js is the architectural core of the AI layer.
- Documents are chunked and embedded using Google’s Gemini embedding model, then stored in Pinecone.
- This creates a retrieval boundary: the system does not rely only on the language model’s memory; it first fetches relevant chunks from the user’s own uploaded documents.
8. AI interaction flow
- aiController is the API surface for document-grounded AI features such as chat and quiz generation.
- Request flow is likely: user question → backend retrieves relevant chunks from Pinecone → Gemini generates answer or quiz grounded in those chunks.
- This means the AI subsystem depends on both the vector store and the original document corpus, with the backend orchestrating the whole response.
9. Authentication and session boundary
- The README indicates JWT-based auth plus Google OAuth.
- authMiddleware protects private routes, so authenticated requests are enforced at the API layer rather than only in the UI.
- The presence of access/refresh secrets in .env.example suggests token-based session management with server-side verification and client-side token storage/usage.
10. External services and infrastructure
- MongoDB: user and document persistence.
- Pinecone: semantic index for retrieval.
- Google Gemini: both generation and embeddings.
- Vercel hosts the frontend; Render hosts the backend.
- The frontend’s vercel.json and README note a proxy/rewrite setup so browser requests can reach the backend under the deployed domain structure.
11. Request/data lifecycle
- A typical lifecycle is:
1. User authenticates through the frontend.
2. The frontend stores auth state and enables protected dashboard routes.
3. User uploads documents through the file manager.
4. Backend parses and stores document metadata.
5. Text is chunked, embedded, and indexed in Pinecone.
6. User asks questions or requests quizzes.
7. Backend retrieves relevant chunks and calls Gemini to generate the result.
- This is the key end-to-end flow to capture in an architecture diagram.
12. Non-runtime artifacts
- docs/ contains deployment notes, API docs, and interview/implementation docs; these are useful for understanding the design but are not runtime components.
- createIndex.js is a setup/provisioning script, likely used to create or initialize the Pinecone index outside normal request handling.
13. Main architectural boundary to show in a diagram
- The most important boundary is between:
- Client/UI: React app, state, routing, theme
- API orchestration: Express controllers and middleware
- Persistence/AI: MongoDB, Pinecone, Gemini
- The backend is the orchestrator that bridges user actions to document storage, semantic retrieval, and model inference.
Main entry points: App.jsx App shell · Dashboard.jsx Dashboard · server.js Server · fileController.js File controller
Components 34
Frontend
React/Vite client application and UI state
- Main entry · Mounts the React app and global providers
frontend/src/main.jsx - App shell · Top-level routing and provider composition
frontend/src/App.jsx - Auth state · Client-side authentication state and session handling
frontend/src/context/AuthContext.jsx - Theme state · Shared UI theme state across the app
frontend/src/context/ThemeContext.jsx - Protected route · Blocks unauthenticated access to private areas
frontend/src/components/ProtectedRoute.jsx - Dashboard layout · Shell for authenticated workspace pages
frontend/src/layouts/DashboardLayout.jsx - Home · Public landing page
frontend/src/pages/Home.jsx - Login · User sign-in screen
frontend/src/pages/Login.jsx - Register · User sign-up screen
frontend/src/pages/Register.jsx - Dashboard · Authenticated workspace entry page
frontend/src/pages/Dashboard.jsx - Overview · Workspace summary and status
frontend/src/pages/dashboard/Overview.jsx - AI chat · Document-grounded conversational interface
frontend/src/pages/dashboard/AIChat.jsx - Files · Upload and document management
frontend/src/pages/dashboard/FileManager.jsx - Study room · Study and quiz workflow
frontend/src/pages/dashboard/StudyRoom.jsx - Calendar · Planning and schedule view
frontend/src/pages/dashboard/CalendarView.jsx - Billing · Subscription and payment area
frontend/src/pages/dashboard/Billing.jsx - Settings · Account and app preferences
frontend/src/pages/dashboard/Settings.jsx - Payment modal · Billing purchase flow dialog
frontend/src/components/PaymentModal.jsx
Backend
Express API, domain logic, and orchestration
- Server · Bootstraps the backend API server
backend/server.js - Auth routes · HTTP routes for authentication
backend/routes/authRoutes.js - File routes · HTTP routes for document upload and file actions
backend/routes/fileRoutes.js - AI routes · HTTP routes for chat and quiz generation
backend/routes/aiRoutes.js - Auth controller · Login, registration, OAuth, and token handling
backend/controllers/authController.js - File controller · Upload intake and document workflow
backend/controllers/fileController.js - AI controller · Document-grounded AI request handling
backend/controllers/aiController.js - Auth middleware · Protects private API routes with JWT checks
backend/middleware/authMiddleware.js - RAG service · Chunking, embeddings, retrieval, and answer assembly
backend/services/ragService.js
Data & AI
Persistence and external AI services
- User model · User identity and auth persistence
backend/models/User.js - Document model · Uploaded document metadata and ownership
backend/models/Document.js - MongoDB · Primary database for users and documents
- Pinecone · Semantic retrieval index for document chunks
- Gemini · Generates answers, quizzes, and embeddings
- Vercel · Hosts the client application
frontend/vercel.json - Render · Hosts the API server
Connections 46
- Main entry → App shell: mounts · Bootstraps the application shell
- App shell → Auth state: uses · Shares authentication state
- App shell → Theme state: uses · Shares theme state
- App shell → Protected route: guards · Restricts private routes
- Protected route → Dashboard layout: opens · Allows access to the dashboard shell
- Dashboard layout → Dashboard: wraps · Provides authenticated workspace chrome
- Dashboard → Overview: navigates · Workspace summary
- Dashboard → AI chat: navigates · Document-grounded chat
- Dashboard → Files: navigates · Uploads and file management
- Dashboard → Study room: navigates · Study and quiz flow
- Dashboard → Calendar: navigates · Scheduling view
- Dashboard → Billing: navigates · Subscription and payments
- Dashboard → Settings: navigates · Account preferences
- Billing → Payment modal: opens · Payment flow dialog
- App shell → Home: routes to · Public entry page
- App shell → Login: routes to · Sign-in page
- App shell → Register: routes to · Sign-up page
- Server → Auth routes: mounts · Registers auth endpoints
- Server → File routes: mounts · Registers file endpoints
- Server → AI routes: mounts · Registers AI endpoints
- Auth routes → Auth controller: dispatches · Forwards auth requests
- File routes → File controller: dispatches · Forwards file requests
- AI routes → AI controller: dispatches · Forwards AI requests
- Auth routes → Auth middleware: protects · Secures private auth-related endpoints
- File routes → Auth middleware: protects · Secures upload and document endpoints
- AI routes → Auth middleware: protects · Secures AI endpoints
- Auth controller → User model: reads/writes · Creates and authenticates users
- File controller → Document model: reads/writes · Stores document metadata
- File controller → RAG service: indexes · Sends uploaded content into retrieval processing
- AI controller → RAG service: queries · Retrieves relevant chunks for responses
- RAG service → Pinecone: searches · Retrieves semantically similar chunks
- RAG service → Gemini: embeds/generates · Creates embeddings and grounded outputs
- User model → MongoDB: persists to · User records stored in MongoDB
- Document model → MongoDB: persists to · Document records stored in MongoDB
- App shell → Server: API calls · Client talks to backend through the API boundary
- App shell → Vercel: deployed on · Frontend hosting target
- Server → Render: deployed on · Backend hosting target
- File controller → MongoDB: metadata · Document metadata is durable in the primary database
- File controller → Pinecone: chunks · Indexes document text for retrieval
- AI controller → Gemini: generates · Uses Gemini for answers and quizzes
- App shell → Auth routes: auth API · Client authentication requests
- App shell → File routes: file API · Client document requests
- App shell → AI routes: ai API · Client AI requests
- Server → MongoDB: connects · Backend database connection
- Server → Pinecone: connects · Backend vector store connection
- Server → Gemini: connects · Backend AI provider connection