Overview
kxinspectbackendpython is a contract-frozen FastAPI mock that implements every rule in docs/contract-v1.md without pretending to be a production service. It exists so the Flutter app can be developed and reviewed against a real HTTP + SSE surface, while also producing the canonical fixture bundle the frontend ships.
Architecture
Layering & dependency rule
Contract v1 (Frozen)
docs/contract-v1.md + docs/openapi-v1.json + docs/contracts/examples/.json + the exported fixture bundle are one artefact. Changing anything here is a G-01 contract change* requiring coordinated edits in both repos — not a file edit.
Domain Logic
Pure, framework-free business rules. Two modules own all student-visible behavior.
Data Models & Schemas
Wire schemas (Pydantic v2 strict)
Store Engine
Not a database. One process, one worker, one os.replace. If you want Postgres, this is not the service — it is a demo store engineered to be trivially auditable.
API Reference
Base URL (local)//127.0.0.1:8000/api/v1 — OpenAPI at /openapi.json and Swagger at /docs. All JSON bodies use strict lowerCamelCase. Single pagination-free list responses in v1; order is explicit.
Envelopes & Errors
Success envelope
Attachments
POST /charges//contest is the only writer of contest attachments; reads are byte-safe downloads. The implementation optimizes for correctness under the single atomic commit, not for scale.
Eventing & SSE
Server-sent events are the live-sync seam between the single-writer store and any number of readers (Flutter LiveSyncService, browser tabs, curl).
Configuration
Every setting is read once at startup via pydantic-settings with envprefix="KX", extra="forbid" and frozen=True. Invalid combination fails fast with a ValueError before the app binds.
Verification
Canonical gates