Grademaxxing - Grade Management System

A full-stack web application for managing grades with flexible grading systems, supporting multiple users, custom grading categories, and report periods.

Features

• 🔐 Multi-user authentication with JWT tokens
• 📚 Flexible subject management with custom grading categories (not limited to German system)
• 📊 Grade tracking with weighted categories
• 📅 Report periods for semester/quarter grades
• 📈 Automatic calculations for category averages and overall GPAs
• 🎨 Modern UI with Tailwind CSS
• 🐳 Fully containerized with Docker Compose

Tech Stack

Frontend:

• React Router 7 (SPA mode)
• TypeScript
• Tailwind CSS v4
• Vite

Backend:

• FastAPI (Python)
• MongoDB (with Motor async driver)
• JWT authentication
• Pydantic validation

Project Structure

grademaxxing/
├── app/                      # Frontend React application
│   ├── api/                  # API client
│   ├── components/           # Reusable UI components
│   ├── routes/               # Page routes
│   ├── types/                # TypeScript types
│   └── utils/                # Utility functions
├── backend/                  # Python FastAPI backend
│   ├── routes/               # API endpoints
│   ├── main.py               # FastAPI application
│   ├── models.py             # Pydantic models
│   ├── database.py           # MongoDB connection
│   ├── auth.py               # Authentication utilities
│   ├── config.py             # Configuration
│   └── requirements.txt      # Python dependencies
├── docker-compose.yml        # Docker Compose configuration
├── Dockerfile.backend        # Backend container
└── Dockerfile                # Frontend container (optional)

Quick Start with Docker

Prerequisites

• Docker
• Docker Compose

Setup

1. Clone the repository

   git clone <repository-url>
   cd grademaxxing
   

2. Create environment file

   cp .env.example .env
   

   Edit .env and configure the following required variables:

   # MongoDB connection string (for Docker use: mongodb://mongodb:27017)
   MONGODB_URL=mongodb://mongodb:27017
   
   # Database name
   DATABASE_NAME=grademaxxing
   
   # JWT Secret Key - GENERATE A SECURE KEY!
   # Run: python -c "import secrets; print(secrets.token_urlsafe(64))"
   SECRET_KEY=your-super-secret-key-change-this-in-production
   
   # Token expiration (30 days = 43200 minutes)
   ACCESS_TOKEN_EXPIRE_MINUTES=43200
   
   # CORS origins
   CORS_ORIGINS=http://localhost:5173,http://localhost:8000,http://127.0.0.1:8000
   

3. Start all services

   docker-compose up --build
   

   This will:

   • Start MongoDB on port 27017
   • Build the frontend
   • Start the Python backend on port 8000
   • Serve the frontend through the backend

4. Access the application

   • Open your browser and navigate to: http://localhost:8000
   • Create an account and start managing your grades!

Docker Services

• mongodb: MongoDB database (port 27017)
• frontend-build: Builds the React SPA (runs once)
• backend: FastAPI server serving API and static files (port 8000)

Stopping Services

# Stop all services
docker-compose down

# Stop and remove volumes (clears database)
docker-compose down -v

Development

For local development without Docker, see DEVELOPMENT.md.

Environment Variables

All configuration is managed through the .env file in the project root.

Required variables:

Variable	Description	Example
MONGODB_URL	MongoDB connection string	mongodb://mongodb:27017 (Docker) mongodb://localhost:27017 (Local)
DATABASE_NAME	Database name	grademaxxing
SECRET_KEY	JWT signing key (keep secure!)	Generate with: python -c "import secrets; print(secrets.token_urlsafe(64))"
ALGORITHM	JWT algorithm	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	Token expiration time	43200 (30 days)
CORS_ORIGINS	Allowed CORS origins (comma-separated)	http://localhost:5173,http://localhost:8000
VITE_API_URL	Frontend API endpoint	http://localhost:8000/api

Note: The .env.example file contains all available variables with documentation.

Usage Guide

1. Create an Account

• Register with email, username, and password
• Login to access your dashboard

2. Create Report Periods

• Go to "Report Periods"
• Define time periods (e.g., "First Semester 2024/2025")
• Set start and end dates

3. Add Subjects

• Click "Add Subject"
• Enter subject name and optional teacher
• Define grading categories with weights (must sum to 100%)
  • Example: "Written" (60%), "Oral" (40%)
  • Or: "Tests" (70%), "Homework" (20%), "Participation" (10%)
• Choose a color for visual identification

4. Add Grades

• Click on a subject
• Add grades with:
  • Name (optional)
  • Category
  • Grade value and maximum
  • Weight within category
  • Date
  • Notes (optional)

5. View Report Cards

• Dashboard shows overall average for selected period
• Report card table displays category and final grades per subject
• Automatic weighted average calculations

API Documentation

Once the backend is running, visit:

• API docs: http://localhost:8000/docs
• Alternative docs: http://localhost:8000/redoc

Main Endpoints

Authentication:

• POST /api/auth/register - Create account
• POST /api/auth/login - Login
• GET /api/auth/me - Get current user

Subjects:

• GET /api/subjects - List subjects
• POST /api/subjects - Create subject
• PUT /api/subjects/{id} - Update subject
• DELETE /api/subjects/{id} - Delete subject

Grades:

• GET /api/grades?subject_id={id} - List grades
• POST /api/grades - Create grade
• PUT /api/grades/{id} - Update grade
• DELETE /api/grades/{id} - Delete grade

Report Periods:

• GET /api/periods - List periods
• POST /api/periods - Create period
• PUT /api/periods/{id} - Update period
• DELETE /api/periods/{id} - Delete period

Building for Production

Using Docker Compose

docker-compose up --build -d

Manual Build

Frontend:

pnpm build

Output: build/client/

Backend:

cd backend
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a pull request.