# arpitkatiyyar/intellistudy_ai architecture

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

- Interactive diagram: https://gitdiagram.com/arpitkatiyyar/intellistudy_ai
- Repository: https://github.com/arpitkatiyyar/intellistudy_ai

## Overview

1. **High-level shape**  
   IntelliStudy AI is a two-tier application: a **React single-page frontend** and an **Express/Node backend API**. The frontend is responsible for the user experience and stateful study UI, while the backend owns authentication, study generation, persistence, file processing, caching, and AI integration.

2. **Frontend boundary**  
   The frontend is organized around **pages, reusable components, layouts, and context/services**.  
   - `pages/` holds route-level screens such as Dashboard, Study, Login, Register, Profile, History, and SessionDetails.  
   - `components/` contains UI widgets like the flashcard player, sidebar, navbar, and question input.  
   - `context/AuthContext.jsx` indicates client-side auth state management.  
   - `services/api.js` is the API boundary from the browser to the backend.

3. **Backend entry and API composition**  
   The backend is structured as a classic Express application with a central app bootstrap and route modules.  
   - `server.js` is the process entry point.  
   - `src/app.js` likely wires middleware, routes, and shared error handling.  
   - Route modules split the API by domain: `auth`, `dashboard`, `study`, `flashcard`, `test`, `analytics`, and `upload`.

4. **Request processing pipeline**  
   Incoming requests pass through middleware before reaching controllers. The backend has explicit boundaries for:  
   - `auth.middleware.js` for protected routes and JWT verification  
   - `rateLimit.middleware.js` for request throttling  
   - `validate.middleware.js` for payload validation against schemas  
   This suggests a layered API where controllers stay thin and domain logic is pushed into services.

5. **Authentication and session security**  
   Auth is not just login/logout; it includes **registration, OTP verification, JWT access tokens, refresh tokens, and HTTP-only cookies**.  
   - Passwords are hashed with bcrypt.  
   - Refresh-token support is persisted in the database, which is reflected by the Prisma migrations.  
   - Redis is used for temporary authentication data such as OTPs or short-lived state.  
   This makes auth a distinct subsystem with both database-backed and cache-backed parts.

6. **Study generation and AI orchestration**  
   The core product feature is a study-content generation pipeline. The backend’s study-related controllers/services turn either a topic/question or extracted document text into:  
   - summaries  
   - flashcards  
   - multiple-choice quizzes  
   - analytics-friendly study data  
   Prompt construction and response parsing are separated into utility/service modules, which suggests the AI layer is treated as an external dependency rather than embedded business logic.

7. **LLM integration boundaries**  
   The repository supports multiple AI backends: **Ollama/Llama 3** and **Google Gemini**.  
   - `gemini.service.js` and `aiService.service.js` imply an abstraction over model providers.  
   - `promptBuilder.js` and `extractJSON.js` indicate the app expects structured model output and normalizes it before persisting or returning it.  
   This abstraction is important in the diagram: the app’s AI layer sits behind a service boundary, not directly inside controllers.

8. **Document upload and text extraction flow**  
   Uploaded study materials are handled separately from plain question input.  
   - `upload.controller.js` and `config/multer.js` manage file ingress.  
   - `utils/pdfExtractor.js`, `utils/documentExtractor.js`, and the README’s support for PDF/DOCX/TXT show a text-extraction pipeline.  
   - The `uploads/` directory is a local filesystem staging area.  
   After extraction, the text is fed into the same AI generation flow as manual prompts.

9. **Persistence layer and domain model**  
   Prisma is the ORM boundary between the backend and **MySQL**.  
   - `prisma/schema.prisma` and multiple migrations show the database is actively used for app state, not just auth.  
   - Migration names reveal key entities/features such as **flashcard progress**, **cascade deletes**, and **refresh tokens**.  
   This suggests persisted study sessions, user-linked flashcards, token records, and progress tracking are central to the data model.

10. **Learning features as separate backend domains**  
   The backend splits the learning experience into functional subsystems:  
   - **Flashcards**: review, known/difficult marking, progress tracking  
   - **Tests/Quizzes**: MCQ generation and answer checking  
   - **Study sessions**: creation, history, and session detail retrieval  
   - **Analytics**: mastery percentage, weak-topic detection, and aggregate stats  
   - **Dashboard**: summary metrics for the user’s study activity  
   These are distinct API domains, even though they share the same user/session data.

11. **Redis as a performance and ephemeral-state layer**  
   Redis is used for more than generic caching. The README and config layout imply it supports:  
   - document analysis cache  
   - OTP storage  
   - temporary authentication/session data  
   - faster repeat AI requests  
   In the architecture diagram, Redis should be shown as an auxiliary store alongside MySQL, not as the primary system of record.

12. **What to show as the main boundaries**  
   For an architecture diagram, the most important boundaries are:  
   - **Browser / React UI**  
   - **Express API layer**  
   - **Middleware/security gate**  
   - **AI orchestration layer**  
   - **File extraction pipeline**  
   - **Prisma/MySQL persistence**  
   - **Redis ephemeral cache**  
   - **External/local model providers** (Ollama, Gemini)  
   - **Local uploads storage**  
   The main data flows are: user input or uploaded document → backend validation/auth → text extraction or prompt building → AI generation → structured response → persistence → analytics/history returned to the frontend.

Main entry points: [`backend/src/routes`](https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/backend/src/routes) (API Routes), [`backend/prisma/schema.prisma`](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/prisma/schema.prisma) (Data Layer), [`backend/src/controllers/study.controller.js`](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/study.controller.js) (Study Domain), [`frontend/src/App.jsx`](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/frontend/src/App.jsx) (React App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["React App<br/>spa<br/>[App.jsx]"]
  node_fe_pages["Pages<br/>route screens"]
  node_fe_ui["UI Components<br/>widgets"]
  node_fe_auth(("Auth State<br/>context<br/>[AuthContext.jsx]"))
  node_fe_api["API Client<br/>[api.js]"]
end

subgraph group_backend["Backend"]
  node_be_entry["Server<br/>entrypoint<br/>[server.js]"]
  node_be_app["Express App<br/>app bootstrap<br/>[app.js]"]
  node_be_mid{{"Middleware<br/>security gate"}}
  node_be_routes["API Routes<br/>route layer"]
  node_be_auth["Auth Domain<br/>controller/service<br/>[auth.controller.js]"]
  node_be_study["Study Domain<br/>controller/service"]
  node_be_flash["Flashcards<br/>learning domain"]
  node_be_test["Tests<br/>learning domain<br/>[test.controller.js]"]
  node_be_analytics["Analytics<br/>learning domain"]
  node_be_upload["Upload Flow<br/>file ingress"]
  node_be_ai{{"AI Orchestrator<br/>service layer"}}
  node_be_extract["Text Extractors<br/>pipeline"]
  node_be_data[("Data Layer<br/>orm config<br/>[schema.prisma]")]
  node_be_cache[("Redis Cache<br/>ephemeral store<br/>[redis.js]")]
  node_be_uploads[("Uploads Dir<br/>filesystem staging")]
end

subgraph group_external["External"]
  node_ext_llm{{"LLMs<br/>providers<br/>[llm.js]"}}
  node_ext_mysql[("MySQL<br/>database")]
end

node_fe_app -->|"routes to"| node_fe_pages
node_fe_app -->|"uses"| node_fe_ui
node_fe_app -->|"reads auth"| node_fe_auth
node_fe_pages -->|"calls"| node_fe_api
node_fe_ui -->|"submits"| node_fe_api
node_be_entry -->|"boots"| node_be_app
node_be_app -->|"applies"| node_be_mid
node_be_app -->|"mounts"| node_be_routes
node_be_routes -->|"dispatches"| node_be_auth
node_be_routes -->|"dispatches"| node_be_study
node_be_routes -->|"dispatches"| node_be_flash
node_be_routes -->|"dispatches"| node_be_test
node_be_routes -->|"dispatches"| node_be_analytics
node_be_routes -->|"dispatches"| node_be_upload
node_be_study -->|"builds prompts"| node_be_ai
node_be_upload -->|"extracts text"| node_be_extract
node_be_ai -->|"invokes"| node_ext_llm
node_be_auth -->|"persists"| node_be_data
node_be_study -->|"persists"| node_be_data
node_be_flash -->|"updates"| node_be_data
node_be_test -->|"reads/writes"| node_be_data
node_be_analytics -->|"aggregates"| node_be_data
node_be_upload -->|"stores files"| node_be_uploads
node_be_auth -->|"uses"| node_be_cache
node_be_study -->|"caches"| node_be_cache
node_be_data -->|"backed by"| node_ext_mysql

click node_fe_app "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/frontend/src/App.jsx"
click node_fe_pages "https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/frontend/src/pages"
click node_fe_ui "https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/frontend/src/components"
click node_fe_auth "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/frontend/src/context/AuthContext.jsx"
click node_fe_api "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/frontend/src/services/api.js"
click node_be_entry "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/server.js"
click node_be_app "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/app.js"
click node_be_mid "https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/backend/src/middleware"
click node_be_routes "https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/backend/src/routes"
click node_be_auth "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/auth.controller.js"
click node_be_study "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/study.controller.js"
click node_be_flash "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/flashcard.controller.js"
click node_be_test "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/test.controller.js"
click node_be_analytics "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/analytics.controller.js"
click node_be_upload "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/upload.controller.js"
click node_be_ai "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/services/aiService.service.js"
click node_be_extract "https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/backend/src/utils"
click node_be_data "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/prisma/schema.prisma"
click node_be_cache "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/config/redis.js"
click node_be_uploads "https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/backend/uploads"
click node_ext_llm "https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/llm.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_fe_app,node_fe_pages,node_fe_ui,node_fe_auth,node_fe_api toneBlue
class node_be_entry,node_be_app,node_be_mid,node_be_routes,node_be_auth,node_be_study,node_be_flash,node_be_test,node_be_analytics,node_be_upload,node_be_ai,node_be_extract,node_be_data,node_be_cache,node_be_uploads toneAmber
class node_ext_llm,node_ext_mysql toneMint
```

## Components

### Frontend

React SPA for study workflows and user-facing state

- [React App](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/frontend/src/App.jsx): spa · Client entry and route shell · `frontend/src/App.jsx`
- [Pages](https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/frontend/src/pages): route screens · Dashboard, study, auth, profile, history, session views · `frontend/src/pages`
- [UI Components](https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/frontend/src/components): widgets · Navbar, sidebar, flashcards, question input · `frontend/src/components`
- [Auth State](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/frontend/src/context/AuthContext.jsx): context · Client-side authentication state and session flow · `frontend/src/context/AuthContext.jsx`
- [API Client](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/frontend/src/services/api.js): service · Browser boundary to backend endpoints · `frontend/src/services/api.js`

### Backend

Express API, services, persistence, and processing pipeline

- [Server](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/server.js): entrypoint · Node process bootstrap · `backend/server.js`
- [Express App](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/app.js): app bootstrap · Middleware and route composition · `backend/src/app.js`
- [Middleware](https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/backend/src/middleware): security gate · Auth, rate limiting, and validation · `backend/src/middleware`
- [API Routes](https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/backend/src/routes): route layer · Domain route modules for auth, study, flashcards, tests, analytics, upload, dashboard · `backend/src/routes`
- [Auth Domain](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/auth.controller.js): controller/service · Registration, OTP, JWT, refresh tokens, email verification · `backend/src/controllers/auth.controller.js`
- [Study Domain](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/study.controller.js): controller/service · Study generation and session orchestration · `backend/src/controllers/study.controller.js`
- [Flashcards](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/flashcard.controller.js): learning domain · Review, progress, and card updates · `backend/src/controllers/flashcard.controller.js`
- [Tests](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/test.controller.js): learning domain · Quiz generation and answer checking · `backend/src/controllers/test.controller.js`
- [Analytics](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/analytics.controller.js): learning domain · Mastery stats, weak topics, and summaries · `backend/src/controllers/analytics.controller.js`
- [Upload Flow](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/controllers/upload.controller.js): file ingress · File intake and document processing entry · `backend/src/controllers/upload.controller.js`
- [AI Orchestrator](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/services/aiService.service.js): service layer · Prompting, provider abstraction, and structured output parsing · `backend/src/services/aiService.service.js`
- [Text Extractors](https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/backend/src/utils): pipeline · PDF and document text extraction plus JSON normalization · `backend/src/utils`
- [Data Layer](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/prisma/schema.prisma): orm config · Prisma schema and MySQL persistence · `backend/prisma/schema.prisma`
- [Redis Cache](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/backend/src/config/redis.js): ephemeral store · OTP, temporary auth state, and cached analysis · `backend/src/config/redis.js`
- [Uploads Dir](https://github.com/arpitkatiyyar/intellistudy_ai/tree/main/backend/uploads): filesystem staging · Local storage for uploaded study files · `backend/uploads`

### External

Datastores and model providers used by the app

- [LLMs](https://github.com/arpitkatiyyar/intellistudy_ai/blob/main/llm.js): providers · Ollama/Llama and Google Gemini backends · `llm.js`
- **MySQL**: database · Primary system of record

## Connections

- React App → Pages: routes to · Renders page-level screens
- React App → UI Components: uses · Composes reusable widgets
- React App → Auth State: reads auth · Uses client auth state
- Pages → API Client: calls · Requests backend data and actions
- UI Components → API Client: submits · User actions invoke API requests
- Server → Express App: boots · Starts the Express app
- Express App → Middleware: applies · Runs cross-cutting middleware
- Express App → API Routes: mounts · Registers domain routers
- API Routes → Auth Domain: dispatches · Auth endpoints
- API Routes → Study Domain: dispatches · Study endpoints
- API Routes → Flashcards: dispatches · Flashcard endpoints
- API Routes → Tests: dispatches · Quiz endpoints
- API Routes → Analytics: dispatches · Analytics endpoints
- API Routes → Upload Flow: dispatches · File upload endpoints
- Study Domain → AI Orchestrator: builds prompts · Orchestrates generation flow
- Upload Flow → Text Extractors: extracts text · Converts uploaded files to study text
- AI Orchestrator → LLMs: invokes · Uses provider backends
- Auth Domain → Data Layer: persists · Users, tokens, and auth records
- Study Domain → Data Layer: persists · Sessions, generated content, progress
- Flashcards → Data Layer: updates · Card progress and review state
- Tests → Data Layer: reads/writes · Quiz attempts and results
- Analytics → Data Layer: aggregates · Computes stats from stored study data
- Upload Flow → Uploads Dir: stores files · Writes uploaded documents locally
- Auth Domain → Redis Cache: uses · OTP and temporary auth state
- Study Domain → Redis Cache: caches · Repeat analysis and intermediate results
- Data Layer → MySQL: backed by · Prisma ORM persistence target