grademaxxing/README.md

# 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**
   ```bash
   git clone <repository-url>
   cd grademaxxing
   ```

2. **Create environment file**
   ```bash
   cp .env.example .env
   ```
   
   Edit `.env` and configure the following required variables:
   
   ```env
   # 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**
   ```bash
   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

```bash
# 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](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)<br>`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
```bash
docker-compose up --build -d
```

### Manual Build

**Frontend:**
```bash
pnpm build
```
Output: `build/client/`

**Backend:**
```bash
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.