Architecture: the 4+1 map

This directory is the map from what the product must do to how it is built. It follows Kruchten's 4+1 model: four views of one system, tied together by the scenarios that motivate them.

Cockburn use case  ──▶  Gherkin feature file  ──▶  pytest-bdd module
   (scenarios view)        (acceptance contract)     (executable proof)
         │
         └──▶  Process view (one diagram per use case)
               Logical, Development, Physical views (one each, system-wide)

Every use case has one page under use-cases/. The page holds the use case in Cockburn form, links the feature files that are its acceptance criteria (they carry the @source:UC-n tag), names the test modules that bind those features, and links the views that realise it. Start from the use case, not from the diagram.

The views

View	Answers	Diagram
Scenarios (+1)	Who uses the system and for what	scenarios/use-cases.puml and the pages under use-cases/
Logical	What the domain is made of and how the code is layered	logical/domain-model.puml, logical/system-components.puml
Process	What happens at runtime, per use case	process/uc-NN-*.puml, one per use case that has runtime behaviour
Development	Where things live in the repository	development/codebase-packages.puml
Physical	Where it runs	physical/production-aws.puml, physical/demo-kubernetes.puml, physical/local-compose.puml

Diagram sources are PlantUML under docs/diagrams/<view>/. make docs renders them and builds the documentation site; make diagrams renders them alone.

The use cases

Use case	Page	Process view
UC-1 Student authenticates and enrols	uc-01	sso-sign-in
UC-2 Student views passport and progress	uc-02	view-passport-offline
UC-3 Student checks in at an event via QR	uc-03	event-qr-checkin
UC-4 Staff verifies a student directly	uc-04	staff-verify
UC-5 Admin builds and edits a challenge	uc-05	challenge-lifecycle
UC-6 Student receives a post-check-in tip	uc-06	post-checkin-tip
UC-7 Student consults the wellness guide	uc-07	guide-guardrails
UC-8 Student completes an assessment	uc-08	mcq-scoring
UC-9 Admin AI-imports a challenge	uc-09	retired, no diagram
UC-10 Admin runs reports and exports	uc-10	reports
UC-11 Admin manages a live event	uc-11	live-event
UC-12 Deploy to another CSU campus	uc-12	stretch, see the physical view
UC-21 Staff send a reminder to students' feed	uc-21	reminders

The functional and non-functional requirements each use case satisfies are catalogued in requirements-and-use-cases.md. Decisions with a history are in adr/.

Scenarios whose behaviour lives in the React app sit under backend/tests/features/frontend/. They are not bound to pytest steps: each names the Vitest spec and test title that proves it, and backend/tests/test_frontend_proofs.py checks every citation resolves.

Keeping it this size

• A story that changes runtime behaviour edits the use case's process diagram. It does not add a diagram.
• A story that changes the data model edits domain-model.puml.
• A new use case gets one page and, if it has runtime behaviour, one process diagram. Its feature files carry @source:UC-n.
• Nothing here is generated. If a page and the code disagree, fix the page in the same pull request.