ClassroomPulse

智慧教室感知、推荐与预约平台

ClassroomPulse turns classroom selection into a transparent decision problem. It combines live seat state, environmental conditions, room facilities and optional location into explainable recommendations, then completes the workflow with seat-level reservation and check-in.

Rebuilt from scratch from an idea explored in a course team project. This repository does not reuse the original source code, database, personal data or model files.

Why this version is different

The project is intentionally designed as a reproducible portfolio system, not as a campus-scale deployment claim:

• one command starts a complete local demo;
• synthetic and device-originated data are visibly distinguished;
• recommendation weights and reasons are exposed to users;
• reservation conflicts are enforced in the domain layer;
• edge device requests are timestamped, HMAC signed and replay protected;
• raw camera video is not required by the server;
• tests cover API, authentication, reservation, security and vision logic;
• no personal data, model weights or private credentials are committed.

Features

Student experience

• Search and filter rooms by building, name and availability.
• View seat occupancy, temperature, humidity, CO₂, noise and illuminance.
• Receive ranked recommendations with human-readable reasons.
• Open a seat map and reserve an available seat.
• Check in during a controlled window or cancel the reservation.
• Install the responsive web interface as a PWA.

Operations and sensing

• Role-protected overview of rooms, seats, reservations and online devices.
• Signed occupancy ingestion for edge vision devices.
• Per-seat confidence, timestamp and data-source provenance.
• Temporal majority smoothing to reduce detector flicker.
• SQLite for zero-configuration demos; PostgreSQL through Docker Compose.

Architecture

flowchart LR
  Browser[Responsive PWA] --> API[FastAPI + domain services]
  API --> DB[(SQLite / PostgreSQL)]
  Camera[Camera + detector] --> Edge[Edge vision agent]
  Edge -->|signed seat observations| API
  API --> Recommend[Explainable recommendation]
  API --> Reserve[Reservation and check-in]

Loading

See architecture details, API overview and data/claim boundaries.

Quick start

Local Python

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements-dev.txt
uvicorn app.main:app --reload --port 8000

Open http://localhost:8000.

Docker Compose

cp .env.example .env
# Replace APP_SECRET, DEVICE_MASTER_SECRET and POSTGRES_PASSWORD in .env.
docker compose up --build

The Docker setup uses PostgreSQL and exposes the app at http://localhost:8000. PowerShell users can run Copy-Item .env.example .env instead of cp. The placeholder secrets are for local setup only and must be replaced before startup; the demo configuration must never be exposed publicly.

Demo accounts

Role	Email	Password
Student	student@classroom.local	Student123!
Administrator	admin@classroom.local	Admin123!

These accounts are created only on an empty demo database.

Edge-agent demo

Start the web application first, then run:

python -m vision.agent --mode synthetic

The agent applies a sliding-window state smoother and submits seat observations to /api/devices/occupancy with a timestamped HMAC signature. Accepted request signatures are retained briefly to reject replays. A real detector can replace the synthetic frame generator without changing the server contract. No detector accuracy is claimed until a documented labelled evaluation set is available.

Tests

pytest -q
node --check app/static/app.js
python -m compileall -q app vision tests
ruff check app vision tests scripts
python scripts/smoke_test.py

Current local result: 16 tests passed.

Project structure

classroom-pulse/
├── app/
│   ├── api/                 # HTTP routes
│   ├── core/                # configuration, database, auth and security
│   ├── services/            # recommendation and reservation rules
│   ├── static/              # responsive PWA
│   ├── main.py
│   ├── models.py
│   ├── schemas.py
│   └── seed.py
├── vision/                  # edge state mapping, smoothing and signed uploader
├── tests/                   # API, security and vision tests
├── docs/                    # architecture, data boundaries and demo guide
├── Dockerfile
├── docker-compose.yml
└── .github/workflows/ci.yml

Data and privacy

All included campus names, coordinates, accounts, room states and sensor values are fictional. The interface labels whether data came from a synthetic seed, demo simulator, reservation action or signed device event. See data-and-privacy.md before adapting the project to a real institution.

Limitations

This is a high-quality educational implementation, not a production-certified campus service. Production use would still require SSO, migrations, rate limits, observability, secret management, accessibility testing, institutional camera approval and evidence-based model evaluation. The roadmap is documented in docs/roadmap.md.

License

MIT License. See LICENSE.