# WatchTower — Lab 01 reference implementation

A complete, minimal reference for Lab 01: local AWS via Floci, idempotent infrastructure, thin
adapters, deterministic seed data, and a verification script that exits non-zero when the platform
is wrong.

This is the expected end state of the lab. It exists to unblock groups and to give instructors a
demo; it is not a substitute for your own requirements document and ADR.

## Quick start

```bash
cp .env.example .env
make up           # start Floci on :4566 and wait until it answers
make bootstrap    # create buckets, tables, queues, log group (idempotent)
make seed         # 3 cameras + 5 clip records
make verify       # acceptance checks; PASS lab-01
make down         # remove resources and stop the emulator
```

`make test` runs unit tests against mocked AWS (`moto`), so it is fast and needs no container.
`make lint` runs Ruff.

## What `make verify` proves

| Check | Evidence |
| --- | --- |
| Buckets | `head-bucket` succeeds for all three |
| Tables | `describe-table` succeeds; events table has the camera/time GSI |
| Queue | redrive policy points at the DLQ with `maxReceiveCount` 5 |
| Logs | `/watchtower/lab1` exists (or `WT_SKIP_LOGS=1` is recorded) |
| S3 | 22-byte object round-trips byte-exact, then is deleted |
| SQS | one message is sent, received and deleted; depth returns to 0 |
| Seed | exactly 3 cameras and 5 clip objects, timestamps preserved |

## Layout

```text
watchtower/
├── compose.yaml          Floci service on :4566
├── Makefile              up · bootstrap · seed · verify · down
├── .env.example          endpoint, region, resource names
├── pyproject.toml        boto3 runtime; pytest, moto, ruff for dev
├── infra/
│   ├── bootstrap.sh      idempotent resource creation
│   └── teardown.sh       exact reverse, safe to re-run
├── src/watchtower/
│   ├── config.py         the only module that reads the environment
│   ├── storage.py        S3 adapter
│   ├── events.py         SQS adapter
│   └── catalog.py        DynamoDB adapter
├── scripts/
│   ├── seed_cameras.py   deterministic 3 cameras / 5 clips
│   └── verify.py         acceptance checks, exit 0/1
├── tests/                adapters under moto
└── docs/
    ├── requirements.md   worked example, not a template to copy blindly
    └── adr/              architecture decision record
```

## Design notes

- **One endpoint, one settings object.** `config.py` is the only place that knows about
  `AWS_ENDPOINT_URL`. Moving to real AWS is deleting one line from `.env`.
- **Adapters accept an injected client.** Tests never touch the network and never depend on the
  emulator.
- **Idempotency is a property, not a retry.** Infrastructure code checks existence before
  creating; the second run prints `=` and exits 0.
- **Verification is code.** `verify.py` is the same script CI will run in Lab 05.
- **Seed data is deterministic.** Fixed IDs and timestamps mean diffs are meaningful.

## Emulator caveats

- CloudWatch Logs is optional in some Floci builds. Set `WT_SKIP_LOGS=1` to record the
  substitution; the rest of the lab is unaffected.
- The web console needs `/var/run/docker.sock`. It is optional; the CLI is the interface.
- Floci is LocalStack-compatible, so any LocalStack example works unchanged.

See `SOLUTION.md` for the instructor walkthrough and the mapping to the grading rubric.
