sacs 0.1.0__tar.gz

sacs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ivanbright
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sacs-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: sacs
+Version: 0.1.0
+Summary: SACS - Smart Academic Coordination System: a real-time multi-tenant school coordination platform with a one-command live demo.
+Author: ivanbright
+License: MIT
+Project-URL: Homepage, https://github.com/ivanbright/sacs
+Project-URL: Repository, https://github.com/ivanbright/sacs
+Project-URL: Issues, https://github.com/ivanbright/sacs/issues
+Project-URL: Changelog, https://github.com/ivanbright/sacs/blob/main/CHANGELOG.md
+Keywords: education,school,timetable,multi-tenant,fastapi,realtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: alembic>=1.13
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: email-validator>=2.0
+Requires-Dist: tzdata>=2024.1; platform_system != "Linux"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Dynamic: license-file
+
+# 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
+
+```bash
+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
+
+| Workspace  | Email                          | Role          | What they can do                                   |
+| ---------- | ------------------------------ | ------------- | -------------------------------------------------- |
+| Platform   | `platform@demo.sacs`           | platform admin | create/suspend/reactivate schools, health, audit   |
+| Head       | `head.northstar@demo.sacs`     | school head   | final approve/reject, staff & academics, bells     |
+| DOS        | `dos.northstar@demo.sacs`      | director of studies | review, forward, return requests; timetable      |
+| Teacher    | `teacher.northstar@demo.sacs`  | teacher       | submit completion requests for own lessons         |
+| Bell       | `bell.northstar@demo.sacs`     | bell monitor  | monitor bell events in real time                   |
+
+(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
+
+| Permission             | school_head | dos | teacher | bell_monitor |
+| ---------------------- | :-: | :-: | :-: | :-: |
+| `school.view`          | ✓ | ✓ | ✓ | ✓ |
+| `school.settings.manage` | ✓ |   |   |   |
+| `staff.manage`         | ✓ |   |   |   |
+| `academics.manage`     | ✓ | ✓ |   |   |
+| `timetable.manage`     | ✓ | ✓ |   |   |
+| `timetable.publish`    | ✓ |   |   |   |
+| `request.submit`       |   |   | ✓ |   |
+| `request.review`       |   | ✓ |   |   |
+| `request.decide`       | ✓ |   |   |   |
+| `bell.view`            | ✓ | ✓ | ✓ | ✓ |
+| `bell.manage`          | ✓ |   |   |   |
+| `audit.view.school`    | ✓ |   |   |   |
+
+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 `BellSchedule`s 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`):
+
+| Variable                  | Default                                   |
+| ------------------------- | ----------------------------------------- |
+| `SACS_HOME`               | `~/.sacs` (demo database lives here)      |
+| `SACS_DATABASE_URL`       | `sqlite:///<SACS_HOME>/sacs.db`           |
+| `SACS_ENV`                | `demo` (`demo`/`dev`/`prod`)              |
+| `SACS_HOST` / `SACS_PORT` | `127.0.0.1` / `0` (auto-pick a free port) |
+| `SACS_ENABLE_TEST_CLOCK`  | `true` (`false` forced in `prod`)         |
+| `SACS_SESSION_TTL_HOURS`  | `12`                                       |
+| `SACS_BELL_GRACE_SECONDS` | `90`                                       |
+
+Deployments can point `SACS_DATABASE_URL` at PostgreSQL (see the `postgres` extra) and run
+`uvicorn sacs.app:create_app --factory`.
+
+## Development
+
+```bash
+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
+```

sacs-0.1.0/README.md

@@ -0,0 +1,181 @@
+# 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
+
+```bash
+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
+
+| Workspace  | Email                          | Role          | What they can do                                   |
+| ---------- | ------------------------------ | ------------- | -------------------------------------------------- |
+| Platform   | `platform@demo.sacs`           | platform admin | create/suspend/reactivate schools, health, audit   |
+| Head       | `head.northstar@demo.sacs`     | school head   | final approve/reject, staff & academics, bells     |
+| DOS        | `dos.northstar@demo.sacs`      | director of studies | review, forward, return requests; timetable      |
+| Teacher    | `teacher.northstar@demo.sacs`  | teacher       | submit completion requests for own lessons         |
+| Bell       | `bell.northstar@demo.sacs`     | bell monitor  | monitor bell events in real time                   |
+
+(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
+
+| Permission             | school_head | dos | teacher | bell_monitor |
+| ---------------------- | :-: | :-: | :-: | :-: |
+| `school.view`          | ✓ | ✓ | ✓ | ✓ |
+| `school.settings.manage` | ✓ |   |   |   |
+| `staff.manage`         | ✓ |   |   |   |
+| `academics.manage`     | ✓ | ✓ |   |   |
+| `timetable.manage`     | ✓ | ✓ |   |   |
+| `timetable.publish`    | ✓ |   |   |   |
+| `request.submit`       |   |   | ✓ |   |
+| `request.review`       |   | ✓ |   |   |
+| `request.decide`       | ✓ |   |   |   |
+| `bell.view`            | ✓ | ✓ | ✓ | ✓ |
+| `bell.manage`          | ✓ |   |   |   |
+| `audit.view.school`    | ✓ |   |   |   |
+
+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 `BellSchedule`s 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`):
+
+| Variable                  | Default                                   |
+| ------------------------- | ----------------------------------------- |
+| `SACS_HOME`               | `~/.sacs` (demo database lives here)      |
+| `SACS_DATABASE_URL`       | `sqlite:///<SACS_HOME>/sacs.db`           |
+| `SACS_ENV`                | `demo` (`demo`/`dev`/`prod`)              |
+| `SACS_HOST` / `SACS_PORT` | `127.0.0.1` / `0` (auto-pick a free port) |
+| `SACS_ENABLE_TEST_CLOCK`  | `true` (`false` forced in `prod`)         |
+| `SACS_SESSION_TTL_HOURS`  | `12`                                       |
+| `SACS_BELL_GRACE_SECONDS` | `90`                                       |
+
+Deployments can point `SACS_DATABASE_URL` at PostgreSQL (see the `postgres` extra) and run
+`uvicorn sacs.app:create_app --factory`.
+
+## Development
+
+```bash
+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
+```

sacs-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sacs"
+version = "0.1.0"
+description = "SACS - Smart Academic Coordination System: a real-time multi-tenant school coordination platform with a one-command live demo."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "ivanbright" }]
+keywords = ["education", "school", "timetable", "multi-tenant", "fastapi", "realtime"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "sqlalchemy>=2.0",
+    "alembic>=1.13",
+    "typer>=0.12",
+    "rich>=13.0",
+    "httpx>=0.27",
+    "email-validator>=2.0",
+    "tzdata>=2024.1; platform_system != 'Linux'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "httpx>=0.27", "build>=1.0", "twine>=5.0"]
+postgres = ["psycopg[binary]>=3.1"]
+
+[project.urls]
+Homepage = "https://github.com/ivanbright/sacs"
+Repository = "https://github.com/ivanbright/sacs"
+Issues = "https://github.com/ivanbright/sacs/issues"
+Changelog = "https://github.com/ivanbright/sacs/blob/main/CHANGELOG.md"
+
+[project.scripts]
+sacs = "sacs.cli:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["sacs", "sacs.*"]
+
+[tool.setuptools.package-data]
+sacs = ["migrations/*", "migrations/versions/*", "alembic.ini"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

sacs-0.1.0/sacs/__init__.py

@@ -0,0 +1,12 @@
+"""SACS - Smart Academic Coordination System.
+
+A real-time, multi-tenant school coordination platform. The package ships a
+Python CLI (``sacs``) that launches a complete local demonstration with five
+simultaneously usable browser workspaces backed by one shared service.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

sacs-0.1.0/sacs/alembic.ini

@@ -0,0 +1,40 @@
+[alembic]
+script_location = sacs/migrations
+prepend_sys_path = .
+version_path_separator = os
+# Overridden programmatically by sacs.db; present for manual `alembic` use.
+sqlalchemy.url = sqlite:///./_migrate_tmp.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

sacs-0.1.0/sacs/app.py

@@ -0,0 +1,97 @@
+"""FastAPI application factory for SACS."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from . import __version__
+from .config import get_settings
+from .db import get_sessionmaker
+from .events import background_dispatcher
+from .scheduler import bell_loop
+
+from .routers import auth as auth_router
+from .routers import academics as academics_router
+from .routers import bell as bell_router
+from .routers import platform as platform_router
+from .routers import realtime as realtime_router
+from .routers import requests as requests_router
+from .routers import schools as schools_router
+from .routers import timetable as timetable_router
+
+
+def cors_urls() -> list[str]:
+    settings = get_settings()
+    origins = list(settings.cors_origins)
+    if settings.env in ("demo", "dev"):
+        origins = ["*"]
+    return origins
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        session_factory = get_sessionmaker()
+        tasks = [
+            bell_loop(session_factory),
+            background_dispatcher(session_factory),
+        ]
+        for task in tasks:
+            app.state.tasks.append(asyncio.create_task(task))
+        yield
+        for task in app.state.tasks:
+            task.cancel()
+        await asyncio.gather(*app.state.tasks, return_exceptions=True)
+
+    app = FastAPI(
+        title="SACS - Smart Academic Coordination System",
+        version=__version__,
+        description="Multi-tenant academic coordination platform: one shared backend, "
+        "isolated school tenants, real-time delivery, and a software bell scheduler.",
+        lifespan=lifespan,
+    )
+    app.state.tasks = []
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cors_urls(),
+        allow_credentials=False,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(schools_router.accept_router)
+    app.include_router(auth_router.router)
+    app.include_router(platform_router.router)
+    app.include_router(schools_router.router)
+    app.include_router(academics_router.router)
+    app.include_router(timetable_router.router)
+    app.include_router(requests_router.router)
+    app.include_router(bell_router.router)
+    app.include_router(bell_router.test_router)
+    app.include_router(realtime_router.router)
+
+    @app.get("/api/health", tags=["system"])
+    def public_health() -> dict:
+        return {"status": "ok", "service": "sacs", "version": __version__}
+
+    @app.get("/", include_in_schema=False)
+    def root() -> dict:
+        return {
+            "service": "sacs",
+            "version": __version__,
+            "docs": "/docs",
+            "health": "/api/health",
+            "note": "No browser frontend is shipped; the SACS CLI is the interface.",
+        }
+
+    return app
+
+
+__all__ = ["create_app"]