ClassOps

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

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

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

2. Create a virtual environment

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

cp .env.example .env

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

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:

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

python app.py

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

Docker quick start

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:

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:

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
• Architecture notes
• Deployment guide
• Public release guide

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md before proposing changes.

Security

Please do not open public issues for vulnerabilities. Use the process in SECURITY.md.

License

This project is licensed under the MIT License.