first commit
This commit is contained in:
Space
237
README.md
Normal file
237
README.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user