SACS — Smart Academic Coordination System

A real-time, multi-tenant school coordination platform that runs entirely from the terminal. SACS coordinates schools (tenants), staff, timetables, lesson sessions, a lesson-completion approval workflow, and a deterministic software bell scheduler, streaming every event to authenticated workspaces over WebSockets.

There is no browser frontend: the whole product is exercised through the sacs CLI, which talks to one shared FastAPI backend exactly like a real client would.

Quick start

pip install sacs          # then:
sacs demo                 # migrate, seed, start the server, open the live dashboard
sacs status               # show whether the demonstration is running
sacs demo reset           # destroy ONLY the local demo database (requires confirmation)
sacs demo stop            # stop the running demonstration
sacs check                # verify dependencies and running environment
sacs version

sacs demo is the product. It:

1. migrates the database to the latest schema (Alembic) and seeds two schools;
2. starts the shared SACS service on a local port;
3. authenticates five independently authorized identities against the real API;
4. shows a live multi-workspace dashboard (Rich) with keyboard commands for the teacher submit → DOS review → head decide workflow, bell operations, and school administration.

The demonstration persists between restarts (sacs demo again keeps your data; use sacs demo reset for a clean slate).

Demo identities

(Pair for riverside-institute: head.riverside@demo.sacs, dos.riverside@demo.sacs, teacher.riverside@demo.sacs, bell.riverside@demo.sacs.)

All demo accounts use the password SacsDemo123!.

The lesson-completion workflow

A teacher submits a completion request for one of their published lessons. The request then moves through a strictly enforced state machine — invalid transitions are rejected server-side:

submitted ──review──> under_dos_review
submitted ──forward─> forwarded_to_head
submitted ──return──> returned_for_correction
under_dos_review ──forward─> forwarded_to_head
under_dos_review ──return──> returned_for_correction
forwarded_to_head ──approve─> approved
forwarded_to_head ──reject──> rejected
returned_for_correction ──submit─> submitted

Every transition records an audit action and the requester-facing history. A secondary-level request may not be final-approved: request.decide (head) and request.review (DOS) are deliberately disjoint.

Roles and permissions

Platform permissions (platform.schools.manage, platform.schools.suspend, platform.health.view, platform.audit.view) are exclusive to platform administrators and never grant academic approval authority.

Bell scheduler

Each school runs BellSchedules with per-period times evaluated in the school's own time zone (Europe/London, America/New_York, …). A background loop ticks once per second; each tick records every due-but-unrecorded occurrence with outcome:

• fired — executed inside the grace window (SACS_BELL_GRACE_SECONDS, default 90);
• missed — the window elapsed while the scheduler was offline;
• skipped — the schedule was paused;
• occurrences are keyed schedule_id + day + period + (start|end) with a unique constraint, so restarts and overlapping ticks can never double-fire the school bell.

Deterministic test clock

In non-production environments the clock can be driven for testing and demonstrations:

POST /api/test/clock/set   { "now_utc": "2026-03-02T10:00:30+00:00" }
POST /api/test/bell/tick
POST /api/test/clock/clear

The test clock is hard-disabled in production unless explicitly enabled.

Real-time events

Every state change is written to a transactional outbox in the same database commit as the change itself, then drained and streamed to the exact recipients allowed server-side by the event audience rule (platform | school roles | specific users). This guarantees a persisted change never silently loses its notification, and gives tests a synchronous delivery path.

Architecture

• API: FastAPI + Pydantic v2, packaged with uvicorn.
• Persistence: SQLAlchemy 2.0 (typed Mapped models); schema only ever created through Alembic migrations — no implicit create_all.
• Auth: opaque hashed session tokens, PBKDF2 password hashing, per-school memberships.
• Tenant isolation: every school-scoped endpoint resolves the caller's membership and re-checks the requested school_id server-side; a suspended school blocks all its members.
• Time handling: all timestamps are UTC; per-school time zones applied only for bell scheduling and local display (tzdata included on Windows).

Configuration

Everything is configurable through environment variables (see sacs/config.py):

Deployments can point SACS_DATABASE_URL at PostgreSQL (see the postgres extra) and run uvicorn sacs.app:create_app --factory.

Development

pip install -e ".[dev]"
pytest                      # full test suite
pytest tests/test_packaging.py   # build wheel/sdist and inspect artifacts
python -m build --no-isolation --outdir dist

Repository layout

sacs/
  cli.py          Typer CLI + the demo dashboard (five workspaces)
  app.py          FastAPI application and lifespan tasks
  models.py       SQLAlchemy models (19 tables)
  db.py           engines, sessions, Alembic wiring
  security.py     password + session token handling
  rbac.py         permission catalog for roles and platform
  workflow.py     the completion-request state machine
  scheduler.py    deterministic clock + bell loop and outcomes
  events.py       connection manager, transactional outbox, dispatcher
  seed.py         idempotent demo seed (two schools, five identities)
  migrations/     Alembic baseline migration
  routers/        platform, schools, academics, timetable, requests, bell, realtime, auth
tests/            unit + API + isolation + scheduler + packaging tests