How afrozahmad07/exam-simulator works
Project type and purpose
• This is a monolithic, full-stack web application called “Exam Simulator.”
• Purpose: allow teachers and students to upload study materials (PDF, DOCX, TXT), generate AI-powered exam questions via OpenAI GPT, administer exams, and track results.
File structure
• Top-level scripts and configs: app.py (Flask entry point), wsgi.py, run.sh, Dockerfile, gunicorn_config.py, various deployment CI/CD guides.
• Core backend code:
• models.py (SQLAlchemy ORM)
• utils.py (common helpers)
• question_generator.py (AI integration)
• import_data.py, export_data.py, migrate_db.py, init_db.py, create_superadmin.py, demo_data.py (DB lifecycle & seeding)
• Presentation layer:
• templates/ (Jinja2 HTML templates for login, register, upload, exam, results, admin dashboards, etc.)
• static/ (style.css, plus any JS/CSS assets)
• File storage: uploads/ directory for user-uploaded documents.
• Tests: test_superadmin.py, test_validators.py, etc.
README insights
• Backend: Flask + SQLAlchemy + Flask-Login
• Frontend: Jinja2 templates styled with Bootstrap 5 and Alpine.js
• Storage: default SQLite (configurable to PostgreSQL)
• AI: OpenAI GPT via environment‐driven API key (utils and question_generator modules)
• Deployment: local (run.sh), Docker, Gunicorn behind Nginx or Virtualmin
• Client Layer: Web browser (HTTP/S)
• Edge/Load Balancer: Nginx or Virtualmin (static file serving, reverse proxy)
• Application Server: Gunicorn workers → Flask app (app.py, wsgi.py)
• Business Logic:
– Routing/controllers in app.py
– Question Generation service (question_generator.py → calls OpenAI API)
– Utilities (utils.py, file parsing with PyPDF2, python-docx)
• Data Layer:
– Relational Database (SQLite or PostgreSQL via SQLAlchemy)
– File Storage (uploads/ directory on disk or network volume)
• External Services:
– OpenAI GPT API (for AI question gen)
1. User → HTTP → Nginx → Gunicorn → Flask router
2. Flask handlers → read/write DB (SQLAlchemy ORM)
3. Flask upload endpoint → save files to uploads/ → process via file-parsing utilities
4. Question-generation endpoint → question_generator.py → HTTP call to OpenAI → receive JSON → store/retrieve from DB
5. Flask → Jinja2 render templates → HTTP response back through Gunicorn → Nginx → Browser
c. Architectural Patterns & Design Principles:
• Monolithic MVC-style layering (Models in models.py, Views in Jinja2 templates, Controllers in app.py)
• Layered architecture: Presentation → Application → Data
• Separation of concerns: upload parsing, AI integration, database migration scripts all live as modular scripts/utilities
• Environment-driven configuration (dotenv, gunicorn_config.py, .env)
d. Key Technologies & Frameworks (annotate in each component):
• Flask, Flask-Login, SQLAlchemy (backend)
• Jinja2, Bootstrap 5, Alpine.js (frontend)
• PyPDF2, python-docx (document processing)
• OpenAI API (AI service)
• SQLite/PostgreSQL (database)
• Gunicorn, Nginx/Docker (deployment)
Details
• Do not omit the uploads/ storage path and its flow from client to disk.
• How question_generator.py connects asynchronously or synchronously to OpenAI.
• Process for session management (Flask-Login).
• Both synchronous user-driven flows (upload → exam → results) and background tasks (data imports/exports, migrations).