🎓 Student Examination Application

📑 Table of Contents

• 📚 Overview
• ✨ Key Features
• 🚀 Getting Started
• 🛠️ Tech Stack
• 📊 Project Structure
• 🔧 Backend Architecture
• 🔒 Environment Configuration
• 🧪 Testing
• 📝 API Documentation
• 👥 Contributors
• 📄 License

📚 Overview

The Student Examination Application is a cutting-edge educational platform designed to revolutionize the way academic institutions handle examinations. Built with modern technologies and a microservices architecture, it offers:

🎯 Purpose

• Streamlined Exam Management: End-to-end solution from exam creation to result analysis
• Paperless Environment: Reduce administrative overhead and environmental impact
• Enhanced Security: Advanced measures to prevent cheating and ensure exam integrity

💡 Core Benefits

• For Students: Easy access to exams, instant results, and progress tracking
• For Teachers: Simplified exam creation, automated grading, and detailed analytics
• For Administrators: Comprehensive oversight, detailed reporting, and efficient management

🌟 Why Choose This Solution?

• Modern Architecture: Built with React 19 and FastAPI for optimal performance
• Scalable Design: Microservices approach allows easy scaling and maintenance
• Real-time Updates: Instant result processing and notification system
• Cross-platform: Works seamlessly across desktop and mobile devices

✨ Key Features

Feature	Description
🔐 Secure Authentication	Complete user management with JWT HTTP-Only cookies
👩‍🏫 Role-Based Access	Separate interfaces for students, teachers, and administrators
📝 Exam Management	Create, assign, take, and grade exams
🤖 Automatic Evaluation	AI-powered automatic grading of exams
🌓 Dark/Light Mode	Customizable UI theme for better user experience
⏱️ Time Zone Handling	Accurate scheduling across different regions
📱 Responsive Design	Works on desktop and mobile devices
📧 Email Notifications	Automated alerts for exam schedules and results

🚀 Getting Started

Prerequisites

• Docker and Docker Compose

Quick Start

1. Clone the repository:

   git clone https://github.com/LilConsul/hell-app.git
   cd hell-app

2. Start the application:

   docker-compose up -d

3. Access the application:

Important

The application runs on self-signed certificates, so you may need to accept the security warning in your browser.

Service	URL
Frontend	https://localhost
API Documentation	https://localhost/api/docs
Email Testing UI	https://localhost/dev/mailhog
Celery Monitoring	https://localhost/dev/flower

🗃️ Testing Database

The project includes a test database backup located in the backup directory. To import this database:

docker compose exec backup /backup/backup.sh

Note

Alternatively, you can use the cli to import the backup, but it is recommended to use the script for convenience.

1. List available backups:

   docker compose exec backup /backup/backup.sh list

2. Restore a specific backup:

   docker compose exec backup /backup/backup.sh restore <backup_name>

🛠️ Tech Stack

Frontend

Backend

Infrastructure

📊 Project Structure

Main Application Code Structure (./src)

src/
├── backend/             # FastAPI application
│   ├── app/
│   │   ├── admin/       # Admin panel functionality
│   │   ├── auth/        # Authentication and authorization
│   │   ├── celery/      # Background task processing
│   │   ├── core/        # Core utilities and base classes
│   │   ├── database/    # Database connections and utilities
│   │   ├── exam/        # Exam management
│   │   ├── middleware/  # Custom middleware components
│   │   └── users/       # User management
│   └── tests/           # Backend tests
├── frontend/            # React application
│   ├── public/          # Static assets
│   └── src/
│       ├── components/  # Reusable UI components
│       ├── contexts/    # React contexts
│       ├── hooks/       # Custom React hooks
│       ├── lib/         # Utility functions
│       └── pages/       # Page components
├── backup/              # Database backup utilities
└── nginx/              # Nginx configuration and SSL

🔧 Backend Architecture

The backend is built with a clean, maintainable three-layer architecture:

Three-Layer Architecture

Layer	Description
🔵 Presentation Layer	FastAPI routers and endpoints that handle HTTP requests and responses. This layer validates input data, manages authentication, and serializes responses.
🟢 Business Logic Layer	Service components that implement core application logic, business rules, and orchestrate workflows between different parts of the system.
🟡 Data Access Layer	Repository pattern implementations that abstract database operations, providing a clean interface for data manipulation without exposing database specifics.

Additional Design Patterns

• Dependency Injection: Leveraging FastAPI's dependency system for loose coupling and easier testing
• Repository Pattern: Abstracting database operations behind interfaces for flexibility in data sources
• Middleware Components: Custom middleware for cross-cutting concerns like language localization and timezone handling
• Asynchronous Processing: Using Celery for handling background tasks and scheduled jobs
• JWT Authentication: Secure authentication using HTTP-only cookies with JWT tokens

The modular design enables independent scaling of components and facilitates continuous development without disrupting existing functionality.

🔒 Environment Configuration

The application uses environment variables for configuration through a .env file. Most variables are self-explanatory, but here are some key ones:

Key Environment Variables

Application Settings

Variable	Description	Example Value
PROJECT_NAME	Name of the application	Hell App
DOMAIN	Domain name for the application	localhost
BACKEND_DEBUG	Enable debug mode for backend	true, false

Security Settings

Variable	Description	Example Value
SECRET_KEY	Secret key for encryption	InsanelySecretKey
ALGORITHM	Algorithm used for JWT	HS256
ACCESS_TOKEN_EXPIRE_SECONDS	JWT token expiration time	36000

Admin Configuration

Variable	Description	Example Value
ADMIN_EMAIL	Admin user email	admin@hell-app.com
ADMIN_PASSWORD	Admin user password	AdminSecret11

Testing Users

These users are used for testing purposes only and should not be used in production. Just leave empty fields if you don't need them.

Variable	Description	Example Value
STUDENT_EMAIL	Test student email	Student123@hell-app.com
STUDENT_PASSWORD	Test student password	StudentSecret11
TEACHER_EMAIL	Test teacher email	Teacher123@hell-app.com
TEACHER_PASSWORD	Test teacher password	TeacherSecret11

Database Configuration (MongoDB)

Variable	Description	Example Value
MONGO_INITDB_ROOT_USERNAME	MongoDB root username	admin
MONGO_INITDB_ROOT_PASSWORD	MongoDB root password	admin
MONGO_INITDB_DATABASE	MongoDB database name	app

🧪 Testing

This project includes comprehensive test coverage for backend functionality.

Running Tests

# Run all tests (command should be executed in the backend container)
uv sync --extra "test" # Install test dependencies
uv run pytest

docker exec hell-app-backend-1 uv sync --extra "test" # Install test, run only once
docker exec hell-app-backend-1 uv run pytest

Test Structure

• Unit tests verify individual components in isolation
• Integration tests ensure different modules work together correctly
• End-to-end tests validate complete user flows

📝 API Documentation

The API documentation is auto-generated using FastAPI's built-in Swagger UI and ReDoc integration.

Documentation	URL
Swagger UI	https://localhost/api/docs
ReDoc	https://localhost/api/redoc

API Endpoints Overview

• /api/auth - Authentication and user management
• /api/exams - Exam creation and management
• /api/students - Student-specific endpoints
• /api/teachers - Teacher-specific endpoints

👥 Contributors

Contributor	Role
Shevchenko Denys	Project Maintainer DevOps Engineer Backend Developer
Yehor Karabanov	Lead Backend Developer
Valerii Matviiv	Frontend Lead Frontend Developer
Marcu Andrei-Alexandru	Intern Frontend Developer
Iana-Iuliana Nastasiu	Intern Frontend Developer

📄 License

MIT License