# afrozahmad07/exam-simulator architecture

> Architecture diagram of the GitHub repository afrozahmad07/exam-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/afrozahmad07/exam-simulator
- Repository: https://github.com/afrozahmad07/exam-simulator

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Web Browser"]:::external
        Templates["Jinja2 Templates"]:::internal
        Static["Static Assets (CSS/JS)"]:::internal
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB

        subgraph "Edge / Load Balancer"
            direction TB
            Nginx["Nginx / Virtualmin"]:::internal
        end

        subgraph "App Server"
            direction TB
            Gunicorn["Gunicorn Workers"]:::internal
            FlaskApp["Flask App"]:::internal
        end

        subgraph "Business Logic"
            direction TB
            UploadProc["Upload & File Processing"]:::internal
            QGen["Question Generation Service"]:::internal
        end

        subgraph "Data Layer"
            direction TB
            DB["Relational DB (SQLite/PostgreSQL)"]:::datastore
            FileStore["File Storage (uploads/)"]:::datastore
            subgraph "DB Lifecycle & Seeding"
                direction TB
                DBInit["Database Init & Migrations"]:::internal
            end
        end

        subgraph "External Services"
            direction TB
            OpenAI["OpenAI GPT API"]:::external
        end
    end

    %% Connections
    Browser -->|"HTTP GET/POST"| Nginx
    Nginx -->|"Proxy to Gunicorn"| Gunicorn
    Gunicorn -->|"WSGI load"| FlaskApp

    FlaskApp -->|"Render HTML"| Templates
    FlaskApp -->|"Serve CSS/JS"| Static

    FlaskApp -->|"SQL INSERT/SELECT"| DB
    FlaskApp -->|"Save files"| FileStore
    FlaskApp -->|"Invoke upload processing"| UploadProc
    FlaskApp -->|"Invoke question gen"| QGen

    UploadProc -->|"Parse PDF/DOCX"| UtilsU[("utils.py")]:::internal
    UploadProc -->|"Store to uploads/"| FileStore

    QGen -->|"Load API key"| UtilsG[("utils.py")]:::internal
    QGen -->|"HTTPS request"| OpenAI
    OpenAI -->|"JSON response"| QGen
    QGen -->|"Store questions"| DB

    DBInit --> DB

    %% Click Events
    click Templates "https://github.com/afrozahmad07/exam-simulator/tree/main/templates/"
    click Static "https://github.com/afrozahmad07/exam-simulator/tree/main/static/"
    click Nginx "https://github.com/afrozahmad07/exam-simulator/blob/main/nginx-virtualmin-config.conf"
    click Gunicorn "https://github.com/afrozahmad07/exam-simulator/blob/main/gunicorn_config.py"
    click FlaskApp "https://github.com/afrozahmad07/exam-simulator/blob/main/app.py"
    click FlaskApp "https://github.com/afrozahmad07/exam-simulator/blob/main/wsgi.py"
    click QGen "https://github.com/afrozahmad07/exam-simulator/blob/main/question_generator.py"
    click UtilsG "https://github.com/afrozahmad07/exam-simulator/blob/main/utils.py"
    click UploadProc "https://github.com/afrozahmad07/exam-simulator/tree/main/uploads/"
    click UtilsU "https://github.com/afrozahmad07/exam-simulator/blob/main/utils.py"
    click DBInit "https://github.com/afrozahmad07/exam-simulator/blob/main/init_db.py"
    click DBInit "https://github.com/afrozahmad07/exam-simulator/blob/main/migrate_db.py"
    click DBInit "https://github.com/afrozahmad07/exam-simulator/blob/main/import_data.py"
    click DBInit "https://github.com/afrozahmad07/exam-simulator/blob/main/export_data.py"
    click DBInit "https://github.com/afrozahmad07/exam-simulator/blob/main/demo_data.py"
    click DBInit "https://github.com/afrozahmad07/exam-simulator/blob/main/create_superadmin.py"
    click DBInit "https://github.com/afrozahmad07/exam-simulator/blob/main/migrate_api_keys.py"
    click DB "https://github.com/afrozahmad07/exam-simulator/blob/main/models.py"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#2980B9,stroke-width:1px
    classDef external fill:#FDEDEC,stroke:#C0392B,stroke-width:1px
    classDef datastore fill:#E9F7EF,stroke:#27AE60,stroke-width:1px
```
