# WatchTower — project labs

One running system, eight labs. The course labs are not eight independent exercises: they build a
single CCTV surveillance platform called **WatchTower**, one chapter at a time, in one repository.

- Lab slides: [`../labs.html`](../labs.html)
- Lab 01 handout: [`lab-01.md`](lab-01.md)
- Lab 01 reference solution: [`lab-01/reference/watchtower/README.md`](lab-01/reference/watchtower/README.md)

## The scenario

A facilities company operates 40 cameras across three sites. It wants automated person and vehicle
events with a 60-second alerting budget, a defensible privacy position, and auditors who can ask
"why did this camera produce that alert?" months later. Students play the platform team.

Every lab produces a working increment plus evidence. The increments accumulate into a system that
is demonstrated end to end in Lab 08.

## Lab map

| Lab | Chapter | Increment | Evidence |
| --- | --- | --- | --- |
| 01 | AI system architecture | Local cloud, repo skeleton, requirements, ADR | `make verify` green from a clean clone |
| 02 | Data engineering | Frame ingestion, sampling, labelling, dataset versioning | Versioned dataset + quality report |
| 03 | Model development | Detector training and day/night evaluation | Model, experiment record, slice metrics |
| 04 | Deployment | Batch scorer and real-time inference service | Latency and throughput benchmark |
| 05 | MLOps automation | CI/CD/CT: test, build, retrain, promote | Green pipeline + auto-registered candidate |
| 06 | Monitoring | Drift, alert quality, dashboards, runbooks | Dashboard + one postmortem |
| 07 | LLMOps | Incident summariser and natural-language event query | Eval set + cost/latency guardrails |
| 08 | Scale and responsibility | Multi-camera scale-out, privacy and audit controls | Load test + privacy impact assessment |

## The lab loop

Every lab uses the same five commands, so the interface never changes and CI can run it:

```bash
make up          # start the local cloud
make bootstrap   # create resources (idempotent)
make seed        # realistic data, generated by code
make verify      # machine-checkable acceptance
make down        # tear everything down
```

Definition of done: a classmate clones the repo, runs `make up && make verify` on a clean machine,
and gets a green result without asking anything.

## Tooling

| Tool | Role |
| --- | --- |
| Docker + Compose v2 | Runs the emulator and, from Lab 04, your services |
| [Floci](https://github.com/floci-io/floci) | Local AWS emulator on `http://localhost:4566` (S3, SQS, DynamoDB, Kinesis, Lambda, CloudWatch, ECR, CodeBuild) |
| AWS CLI v2 / boto3 | Same API calls as production, pointed at the emulator |
| Python 3.11 | Adapters, seed and verification scripts |
| Make | The stable interface for every lab |
| MLflow (Lab 03+) | Experiment tracking and model registry |
| YOLOv8n (Lab 03+) | Detector fine-tuning on a single GPU |
| Prometheus + Grafana (Lab 06+) | Metrics, dashboards, alerts |

Floci is a drop-in replacement for LocalStack: same port, same SDK surface. Any non-empty
credentials work, and no account or auth token is needed.

## Hardware

- Labs 01, 02, 04–08: laptop-class CPU is enough.
- Lab 03: one T4-class GPU (or a cloud notebook). YOLOv8n fine-tuning on ~2k frames takes
  15–20 minutes. Later labs consume precomputed detections so they stay CPU-cheap.
- Disk: ~8 GB for the emulator images plus ~5 GB for clips and datasets.

## Data and licensing

The lab dataset ("WatchTower CCTV mini") is assembled from public surveillance benchmarks plus
synthetic night variants:

- MOT17 / MOT20 sequences — teaching and research use, CC BY-NC-SA. Attribute, do not redistribute.
- CAVIAR clips — research-use terms; download at lab time rather than vendoring.

Lab 02 downloads the data into `wt-raw` and records provenance and licence in the dataset card.
Nothing is committed to the course repository. Groups that cannot download may use the synthetic
generator, which produces the same directory and label layout.

## Reference solutions

Each lab ships a complete reference implementation under `labs/lab-XX/reference/`. Lab 01 is
included here; later labs add theirs as the course runs. It is the expected end state, used for
instructor demos and for unblocking groups. It is not a substitute for the lab: the ADR and the
evidence are still the student's work.

Reference solutions are intentionally small and dependency-light. Where a real product would use a
managed service, the reference uses the emulator equivalent so the whole thing runs offline.

## Assessment

| Weight | Criterion | Full marks |
| --- | --- | --- |
| 40% | Reproducibility | clean clone → green `make verify`, no manual steps |
| 20% | Design decisions | ADR names options, trade-off, consequence |
| 20% | Code and tests | small adapters, tested failure paths |
| 20% | Reflection | what broke, how it was detected, which control prevents recurrence |

The system dossier (`docs/` in the student repo) accumulates requirements, ADRs, evaluation
reports, runbooks and the privacy assessment. It is the revision material for the Lab 08
walkthrough.
