How shreysoni1102-cell/qnario works
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: server.js Server · auth.js Auth routes · app.py Flask app · docker-compose.yml Compose
Components 20
qnario app
Main Node.js application and its browser-facing workflow
- Server · Central backend entry point serving pages, APIs, and realtime exam sessions
qnario/server.js - Auth routes · Login, signup, reset, and session-related endpoints
qnario/routes/auth.js - Enhanced auth · Extended authentication and account flows
qnario/routes/auth-enhanced.js - Exam API · Exam creation, participation, results, and analytics endpoints
qnario/routes/exam-api.js - Auth guard · JWT and role-based route protection
qnario/middleware/auth.js - Rate limit · Abuse protection for sensitive endpoints
qnario/middleware/rateLimiter.js - AI client · HTTP bridge from Node to the Python AI service
qnario/utils/ai-client.js - Email service · Email delivery for password reset and related flows
qnario/services/emailService.js - State backup · Crash recovery and snapshot storage for session state
qnario/storage-utils.js
UI flows
Static pages organized by role and exam workflow
- Teacher UI · Teacher dashboards, exam creation, syllabus upload, analytics, and paper review
qnario/teacher-dashboard.html - Student UI · Student login, practice, quizzes, live exams, results, and review pages
qnario/student-dashboard.html - Admin UI · Admin login and dashboard pages
qnario/admin-dashboard.html - Landing 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 · Core persistence models for users, exams, results, analytics, and generated questions
qnario/models - Mongo config · Database connection configuration
qnario/config/db.js
AI service
Separate Flask service for document parsing and question generation
- Flask app · AI microservice entry point
gemini-microservice/app.py - Gemini service · PDF/text extraction and model-backed question generation
gemini-microservice/gemini_service.py - AI config · Service configuration and model settings
gemini-microservice/config.py
Ops
Setup, seeding, and deployment support
- Setup scripts · Admin setup, database init, and seed utilities
qnario/init-database.js - Compose · Runs the Node app and Python service together
docker-compose.yml
Connections 21
- 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