# shreysoni1102-cell/qnario architecture

> Architecture diagram of the GitHub repository shreysoni1102-cell/qnario, 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/shreysoni1102-cell/qnario
- Repository: https://github.com/shreysoni1102-cell/qnario

## Overview

1. **Top-level shape**
   - This repo is split into two runtime services: **`qnario/`** is the main product server, and **`gemini-microservice/`** is a separate Python AI service.
   - The browser talks to the Node app over **HTTP** and **Socket.IO/WebSockets**; the Node app talks to the Python service over **HTTP** for AI-related work.

2. **Browser/UI layer**
   - The UI is mostly **static HTML, CSS, and vanilla JavaScript**, not a SPA framework.
   - Pages are organized by role and workflow: landing/login/signup, **admin**, **teacher**, and **student** experiences, including exam creation, live exam, quizzes, syllabus upload, analytics, and result review.

3. **Main application server**
   - `qnario/server.js` is the central backend entry point.
   - The server likely serves the static pages, exposes REST endpoints, and manages real-time exam sessions and proctoring events.

4. **API and route boundaries**
   - `qnario/routes/auth.js`, `auth-enhanced.js`, and `exam-api.js` separate authentication from exam/execution flows.
   - This is the main boundary for business logic: login/signup/password reset, exam creation, exam participation, results, and analytics.

5. **Real-time exam/proctoring flow**
   - Socket.IO is used for live session events between students and the teacher dashboard.
   - The README indicates events such as tab switching, idle time, anomalies, force-end, and auto-submit are pushed in real time to the teacher side.

6. **Persistence layer**
   - MongoDB is the primary database, accessed through Mongoose models in `qnario/models/`.
   - The domain model is fairly rich: `User`, `Subject`, `Topic`, `Question`, `Exam`, `ExamSchedule`, `GeneratedQuestion`, `StudentAttempt`, `StudentResult`, and `Analytics`.

7. **AI generation pipeline**
   - Teacher syllabus upload and AI question generation are offloaded to `gemini-microservice/`.
   - That service is a **Flask** app that handles PDF/text extraction and model calls, using **Google Gemini 1.5 Flash** and **Groq Llama3-70b** per the README.

8. **Cross-service contract**
   - `qnario/utils/ai-client.js` is the likely integration point from Node to the Python AI service.
   - This split is an important architecture boundary: the AI workload is isolated so PDF parsing and model latency do not block live exam WebSocket handling.

9. **State recovery and local backup**
   - The project includes `storage-utils.js`, `generated-questions.json`, and README-described crash recovery via periodic snapshots.
   - That means exam/session state is not only in MongoDB; there is also filesystem-backed state used for quick restore after restarts.

10. **Security and session control**
   - Authentication is JWT-based with bcrypt password hashing, plus middleware for auth and rate limiting.
   - `qnario/middleware/auth.js` and `rateLimiter.js` protect protected routes and reduce abuse; role-based flows are implied by separate teacher/admin/student pages.

11. **Support services and admin ops**
   - `qnario/services/emailService.js` handles email-based flows such as password reset.
   - The repo also includes scripts for admin setup/reset and DB seeding, which suggests operational bootstrapping is part of the architecture rather than an afterthought.

12. **Deployment and verification**
   - `docker-compose.yml` runs both services together, each with its own `.env`.
   - GitHub Actions CI and the separate Node/Python test suites show the architecture is intentionally split and validated at both service boundaries.

Main entry points: [`qnario/server.js`](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/server.js) (Server), [`qnario/routes/auth.js`](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/routes/auth.js) (Auth routes), [`gemini-microservice/app.py`](https://github.com/shreysoni1102-cell/qnario/blob/main/gemini-microservice/app.py) (Flask app), [`docker-compose.yml`](https://github.com/shreysoni1102-cell/qnario/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_qnario["qnario app"]
  node_qnario_server["Server<br/>Node entry<br/>[server.js]"]
  node_qnario_routes_auth["Auth routes<br/>HTTP routes<br/>[auth.js]"]
  node_qnario_routes_auth_enhanced["Enhanced auth<br/>HTTP routes<br/>[auth-enhanced.js]"]
  node_qnario_routes_exam_api["Exam API<br/>HTTP routes<br/>[exam-api.js]"]
  node_qnario_middleware_auth["Auth guard<br/>Middleware<br/>[auth.js]"]
  node_qnario_middleware_rate["Rate limit<br/>Middleware<br/>[rateLimiter.js]"]
  node_qnario_utils_ai_client["AI client<br/>Integration client<br/>[ai-client.js]"]
  node_qnario_services_email["Email service<br/>Support service<br/>[emailService.js]"]
  node_qnario_storage_utils["State backup<br/>Filesystem state<br/>[storage-utils.js]"]
end

subgraph group_group_ui["UI flows"]
  node_qnario_ui_teacher["Teacher UI<br/>Static pages"]
  node_qnario_ui_student["Student UI<br/>Static pages"]
  node_qnario_ui_admin["Admin UI<br/>Static pages"]
  node_qnario_ui_entry["Landing pages<br/>Static pages<br/>[index.html]"]
end

subgraph group_group_data["Data layer"]
  node_qnario_models[("Mongo models<br/>Mongoose domain")]
  node_qnario_config_db["Mongo config<br/>DB config<br/>[db.js]"]
end

subgraph group_group_ai["AI service"]
  node_gemini_app["Flask app<br/>Python entry<br/>[app.py]"]
  node_gemini_service["Gemini service<br/>AI pipeline<br/>[gemini_service.py]"]
  node_gemini_config["AI config<br/>Python config<br/>[config.py]"]
end

subgraph group_group_ops["Ops"]
  node_ops_setup["Setup scripts<br/>Bootstrap ops<br/>[init-database.js]"]
  node_ops_deploy["Compose<br/>Deployment<br/>[docker-compose.yml]"]
end

node_qnario_ui_entry -->|"HTTP"| node_qnario_server
node_qnario_ui_admin -->|"HTTP"| node_qnario_server
node_qnario_ui_teacher -->|"HTTP + Socket.IO"| node_qnario_server
node_qnario_ui_student -->|"HTTP + Socket.IO"| node_qnario_server
node_qnario_server -->|"mounts"| node_qnario_routes_auth
node_qnario_server -->|"mounts"| node_qnario_routes_auth_enhanced
node_qnario_server -->|"mounts"| node_qnario_routes_exam_api
node_qnario_routes_auth -->|"protected by"| node_qnario_middleware_auth
node_qnario_routes_exam_api -->|"protected by"| node_qnario_middleware_auth
node_qnario_routes_auth -->|"limited by"| node_qnario_middleware_rate
node_qnario_server -->|"reads/writes"| node_qnario_models
node_qnario_server -->|"connects"| node_qnario_config_db
node_qnario_server -->|"snapshots"| node_qnario_storage_utils
node_qnario_server -->|"sends mail"| node_qnario_services_email
node_qnario_server -->|"calls"| node_qnario_utils_ai_client
node_qnario_utils_ai_client -->|"HTTP"| node_gemini_app
node_gemini_app -->|"delegates"| node_gemini_service
node_gemini_service -->|"uses"| node_gemini_config
node_ops_deploy -->|"starts"| node_qnario_server
node_ops_deploy -->|"starts"| node_gemini_app
node_ops_setup -->|"seeds"| node_qnario_models

click node_qnario_server "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/server.js"
click node_qnario_routes_auth "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/routes/auth.js"
click node_qnario_routes_auth_enhanced "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/routes/auth-enhanced.js"
click node_qnario_routes_exam_api "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/routes/exam-api.js"
click node_qnario_middleware_auth "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/middleware/auth.js"
click node_qnario_middleware_rate "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/middleware/rateLimiter.js"
click node_qnario_utils_ai_client "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/utils/ai-client.js"
click node_qnario_services_email "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/services/emailService.js"
click node_qnario_storage_utils "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/storage-utils.js"
click node_qnario_models "https://github.com/shreysoni1102-cell/qnario/tree/main/qnario/models"
click node_qnario_config_db "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/config/db.js"
click node_qnario_ui_teacher "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/teacher-dashboard.html"
click node_qnario_ui_student "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/student-dashboard.html"
click node_qnario_ui_admin "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/admin-dashboard.html"
click node_qnario_ui_entry "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/index.html"
click node_gemini_app "https://github.com/shreysoni1102-cell/qnario/blob/main/gemini-microservice/app.py"
click node_gemini_service "https://github.com/shreysoni1102-cell/qnario/blob/main/gemini-microservice/gemini_service.py"
click node_gemini_config "https://github.com/shreysoni1102-cell/qnario/blob/main/gemini-microservice/config.py"
click node_ops_setup "https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/init-database.js"
click node_ops_deploy "https://github.com/shreysoni1102-cell/qnario/blob/main/docker-compose.yml"

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_qnario_server,node_qnario_routes_auth,node_qnario_routes_auth_enhanced,node_qnario_routes_exam_api,node_qnario_middleware_auth,node_qnario_middleware_rate,node_qnario_utils_ai_client,node_qnario_services_email,node_qnario_storage_utils toneBlue
class node_qnario_ui_teacher,node_qnario_ui_student,node_qnario_ui_admin,node_qnario_ui_entry toneAmber
class node_qnario_models,node_qnario_config_db toneMint
class node_gemini_app,node_gemini_service,node_gemini_config toneRose
class node_ops_setup,node_ops_deploy toneIndigo
```

## Components

### qnario app

Main Node.js application and its browser-facing workflow

- [Server](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/server.js): Node entry · Central backend entry point serving pages, APIs, and realtime exam sessions · `qnario/server.js`
- [Auth routes](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/routes/auth.js): HTTP routes · Login, signup, reset, and session-related endpoints · `qnario/routes/auth.js`
- [Enhanced auth](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/routes/auth-enhanced.js): HTTP routes · Extended authentication and account flows · `qnario/routes/auth-enhanced.js`
- [Exam API](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/routes/exam-api.js): HTTP routes · Exam creation, participation, results, and analytics endpoints · `qnario/routes/exam-api.js`
- [Auth guard](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/middleware/auth.js): Middleware · JWT and role-based route protection · `qnario/middleware/auth.js`
- [Rate limit](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/middleware/rateLimiter.js): Middleware · Abuse protection for sensitive endpoints · `qnario/middleware/rateLimiter.js`
- [AI client](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/utils/ai-client.js): Integration client · HTTP bridge from Node to the Python AI service · `qnario/utils/ai-client.js`
- [Email service](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/services/emailService.js): Support service · Email delivery for password reset and related flows · `qnario/services/emailService.js`
- [State backup](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/storage-utils.js): Filesystem state · Crash recovery and snapshot storage for session state · `qnario/storage-utils.js`

### UI flows

Static pages organized by role and exam workflow

- [Teacher UI](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/teacher-dashboard.html): Static pages · Teacher dashboards, exam creation, syllabus upload, analytics, and paper review · `qnario/teacher-dashboard.html`
- [Student UI](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/student-dashboard.html): Static pages · Student login, practice, quizzes, live exams, results, and review pages · `qnario/student-dashboard.html`
- [Admin UI](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/admin-dashboard.html): Static pages · Admin login and dashboard pages · `qnario/admin-dashboard.html`
- [Landing pages](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/index.html): Static pages · Public entry pages for landing, signup, role selection, and password recovery · `qnario/index.html`

### Data layer

Mongo models and local state used by the main app

- [Mongo models](https://github.com/shreysoni1102-cell/qnario/tree/main/qnario/models): Mongoose domain · Core persistence models for users, exams, results, analytics, and generated questions · `qnario/models`
- [Mongo config](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/config/db.js): DB config · Database connection configuration · `qnario/config/db.js`

### AI service

Separate Flask service for document parsing and question generation

- [Flask app](https://github.com/shreysoni1102-cell/qnario/blob/main/gemini-microservice/app.py): Python entry · AI microservice entry point · `gemini-microservice/app.py`
- [Gemini service](https://github.com/shreysoni1102-cell/qnario/blob/main/gemini-microservice/gemini_service.py): AI pipeline · PDF/text extraction and model-backed question generation · `gemini-microservice/gemini_service.py`
- [AI config](https://github.com/shreysoni1102-cell/qnario/blob/main/gemini-microservice/config.py): Python config · Service configuration and model settings · `gemini-microservice/config.py`

### Ops

Setup, seeding, and deployment support

- [Setup scripts](https://github.com/shreysoni1102-cell/qnario/blob/main/qnario/init-database.js): Bootstrap ops · Admin setup, database init, and seed utilities · `qnario/init-database.js`
- [Compose](https://github.com/shreysoni1102-cell/qnario/blob/main/docker-compose.yml): Deployment · Runs the Node app and Python service together · `docker-compose.yml`

## Connections

- Landing pages → Server: HTTP · Public pages are served by the main app
- Admin UI → Server: HTTP · Admin workflows use the backend APIs and sessions
- Teacher UI → Server: HTTP + Socket.IO · Teacher dashboard drives live exam and proctoring flows
- Student UI → Server: HTTP + Socket.IO · Students submit attempts and receive realtime exam events
- Server → Auth routes: mounts · Auth endpoints are exposed from the central server
- Server → Enhanced auth: mounts · Extended auth endpoints are exposed from the central server
- Server → Exam API: mounts · Exam and analytics endpoints are exposed from the central server
- Auth routes → Auth guard: protected by · Protected account operations use auth middleware
- Exam API → Auth guard: protected by · Exam operations require authenticated roles
- Auth routes → Rate limit: limited by · Sensitive auth flows are rate limited
- Server → Mongo models: reads/writes · Business logic persists and queries domain data
- Server → Mongo config: connects · Server initializes the MongoDB connection
- Server → State backup: snapshots · Session state is periodically backed up to disk
- Server → Email service: sends mail · Password reset and account flows trigger email delivery
- Server → AI client: calls · AI-assisted generation is delegated to the integration client
- AI client → Flask app: HTTP · Node calls the Python microservice over HTTP
- Flask app → Gemini service: delegates · Flask entry point hands work to the AI pipeline
- Gemini service → AI config: uses · Model and runtime settings are loaded from config
- Compose → Server: starts · Docker Compose runs the Node application
- Compose → Flask app: starts · Docker Compose runs the Python AI service
- Setup scripts → Mongo models: seeds · Setup scripts populate the database and admin state
