# ClassOps

**Repository Path**: Ay_you/ClassOps

## Basic Information

- **Project Name**: ClassOps
- **Description**: Open-source Flask backend for class operations and student workflow management
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ClassOps

[![CI](https://github.com/kipp7/ClassOps/actions/workflows/ci.yml/badge.svg)](https://github.com/kipp7/ClassOps/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Flask](https://img.shields.io/badge/Flask-3.x-000000?logo=flask&logoColor=white)](https://flask.palletsprojects.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

ClassOps is a Flask-based class operations management backend for announcements, activities, attendance leave workflows, course management, enrollment records, file uploads, and password reset email flows.

> Runtime secrets and environment-specific settings are intentionally kept outside version control.

## Features

- User registration, login, role assignment, and committee type management
- Announcement publishing and category management
- Activity creation, listing, and attachment metadata support
- Attendance leave applications, approval workflow, CSV export, and weekly monitor rotation
- Course and enrollment APIs for teacher/student workflows
- File upload endpoint with extension allow-listing
- Email-based password reset and verification code flows

## Tech Stack

- **Backend:** Flask, Flask-CORS, Flask-SQLAlchemy, Flask-Mail
- **Database:** MySQL / MariaDB via PyMySQL
- **Server:** Gunicorn-compatible WSGI entry point
- **Language:** Python 3.10+

## Project Structure

```text
ClassOps/
├── Dockerfile
├── docker-compose.yml
├── Makefile
├── backend/
│   ├── app.py                  # Local development entry point
│   ├── wsgi.py                 # Production WSGI entry point
│   ├── requirements.txt        # Python dependencies
│   ├── .env.example            # Example runtime configuration
│   ├── tests/                  # Backend smoke tests
│   └── app/
│       ├── __init__.py         # Flask app factory
│       ├── config.py           # Environment-driven configuration
│       ├── models.py           # SQLAlchemy models
│       └── routes/             # API blueprints
├── .github/                    # GitHub templates and CI
├── .gitignore
├── LICENSE
└── README.md
```

## Quick Start

### 1. Clone and enter the project

```bash
git clone https://github.com/kipp7/ClassOps.git
cd ClassOps/backend
```

### 2. Create a virtual environment

```bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt
```

### 3. Configure environment variables

```bash
cp .env.example .env
```

Edit `.env` with your local database credentials, mail account, and secret key:

```env
SECRET_KEY=replace-with-a-long-random-secret
DATABASE_URL=mysql+pymysql://classuser:replace-with-password@localhost/classops
MAIL_USERNAME=your-email@example.com
MAIL_PASSWORD=replace-with-mail-app-password
```

### 4. Prepare the database

Create a MySQL database named `classops`, then initialize tables from a Flask shell or a short script:

```bash
python - <<'PY'
from app import create_app
from app.models import db

app = create_app()
with app.app_context():
    db.create_all()
PY
```

### 5. Run locally

```bash
python app.py
```

The API server listens on `http://localhost:5200` by default.

### Docker quick start

```bash
docker compose up --build
```

The container exposes the API at `http://localhost:5200` and stores local SQLite data plus uploads in a named Docker volume.

## Testing

Run the backend quality checks before opening a pull request:

```bash
python -m compileall backend/app backend/app.py backend/wsgi.py
cd backend
pytest -q
```

If `make` is available, the same validation can be run with:

```bash
make test
```

## API Overview

All blueprints are mounted under `/classapi`.

| Area | Representative endpoints |
| --- | --- |
| Auth | `POST /classapi/login`, `POST /classapi/register`, `POST /classapi/forgot-password` |
| Health | `GET /health` |
| Users | `GET /classapi/users`, `POST /classapi/set_role`, `POST /classapi/set_committee_type` |
| Notices | `GET /classapi/notices`, `POST /classapi/notices`, `DELETE /classapi/notices/<id>` |
| Activities | `GET /classapi/activities`, `POST /classapi/activities`, `DELETE /classapi/activities/<id>` |
| Attendance | `GET /classapi/applications`, `POST /classapi/inform`, `GET /classapi/export` |
| Courses | `GET /classapi/courses`, `POST /classapi/courses`, `PUT /classapi/courses/<id>` |
| Enrollments | `GET /classapi/enrollments`, `POST /classapi/enrollments`, `DELETE /classapi/enrollments` |
| Uploads | `POST /classapi/upload` |

## Configuration

| Variable | Purpose | Default |
| --- | --- | --- |
| `SECRET_KEY` | Token signing and session security | `change-me-in-development` |
| `DATABASE_URL` | SQLAlchemy database connection string | local SQLite development database |
| `UPLOAD_FOLDER` | Folder for uploaded files | `backend/uploads` |
| `MAX_CONTENT_LENGTH` | Maximum upload size in bytes | `104857600` |
| `HOST` | Local development bind host | `0.0.0.0` |
| `PORT` | Local development port | `5200` |
| `FLASK_DEBUG` | Enable Flask debug mode | `false` |
| `PRINT_ROUTES` | Print registered routes on startup | `false` |
| `AUTO_CREATE_TABLES` | Create database tables on application startup | `false` |
| `CORS_ORIGINS` | Allowed CORS origins | `*` |
| `MAIL_SERVER` | SMTP host | `smtp.qq.com` |
| `MAIL_PORT` | SMTP port | `465` |
| `MAIL_USE_SSL` | Use SSL for SMTP | `true` |
| `MAIL_USERNAME` | SMTP username | unset |
| `MAIL_PASSWORD` | SMTP app password | unset |
| `MAIL_DEFAULT_SENDER` | Sender address | `MAIL_USERNAME` |
| `FRONTEND_RESET_PASSWORD_URL` | Password reset page URL | `http://localhost:1020/reset-password` |

## Public Release Checklist

- Rotate any credentials that were previously committed or shared during development.
- Rewrite or archive private history before changing visibility if sensitive values existed in older commits.
- Keep `.env`, uploads, logs, virtual environments, and editor files out of Git.
- Confirm the GitHub repository description, topics, and visibility before announcing the project.
- Review open issues and remove private deployment notes before the first public release.

## Documentation

- [API overview](docs/API.md)
- [Architecture notes](docs/ARCHITECTURE.md)
- [Deployment guide](docs/DEPLOYMENT.md)
- [Public release guide](docs/PUBLIC_RELEASE.md)

## Contributing

Issues and pull requests are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes.

## Security

Please do not open public issues for vulnerabilities. Use the process in [SECURITY.md](SECURITY.md).

## License

This project is licensed under the [MIT License](LICENSE).