Capstone starter pack — AI tagging on R2, the NAS and OpenRouter
The starter pack for the capstone: design and prototype the next phase of the campus media unit's catalogue. Add AI tagging to 5,000 assets, with a governance rule, inside a fixed monthly budget, using:
- Cloudflare R2 for the canonical catalogue and tags (private) and the
thumbnails (public, behind
media.<root>); - the Nextcloud/RAID NAS as the local origin and backup for the 5,000 originals;
- the S4 Worker, extended with a tag-ingest route, as the catalogue API and the write gate;
- OpenRouter as the governed managed-inference path.
You choose the tagging method — managed inference, the fine-tuned Qwen3.5-4B, or the S10 classifier — and justify it in the proposal. Every implementation includes one refused and one accepted governed OpenRouter request, and every record passes the Worker's gate.
This pack is a starting point, not the answer: replace the canned offline stub with your method, extend the rule's vocabulary, and build your own evidence.
Architecture — what each piece does
originals + backup canonical catalogue + tags
┌──────────────────────────┐ ┌──────────────────────────────┐
│ Nextcloud on RAID1 NAS │ │ private R2: capstone- │
│ /srv/nas/nextcloud │ │ catalogue (Worker binding) │
└────────────┬─────────────┘ └──────────────┬───────────────┘
│ rclone backup │ validated writes
▼ │
┌──────────────────────────┐ ┌──────────────┴───────────────┐
│ private R2 backup │ │ Worker: /health, /assets, │
│ capstone-nas-backup │ │ /asset/:id, /ingest/tags │
└──────────────────────────┘ └──────────────┬───────────────┘
│ reads tags
┌──────────────────────────┐ ┌──────────────┴───────────────┐
│ tag.py (laptop/Droplet) │─────────▶│ OpenRouter, ZDR + deny │
│ preflight → batch 100 │ governed │ data_collection, no │
│ → validate → post │ request │ fallbacks │
└──────────────────────────┘ └──────────────────────────────┘
| Piece | Holds | Visibility |
|---|---|---|
capstone-catalogue (R2) |
catalogue.json, tags.json, private files |
Worker binding only |
capstone-media-public (R2) |
thumbs/*.png |
public, R2 custom domain media.<root> |
NAS /srv/nas |
the 5,000 originals, Nextcloud data | private network, nas.<root> |
Worker capstone-catalogue |
API + ingest gate | workers.dev or a custom domain |
tag.py |
the pipeline and its checkpoints | your laptop or the Droplet |
Two R2 buckets, because an R2 custom domain exposes every key in the bucket it is attached to. Public thumbnails and the private catalogue cannot share one.
What to run, in what order
COMMANDS.md is the authoritative sequence: every command, in
order, with an explanation. The short version for the local profile:
python3 -m unittest discover -s tests
npm install && npm test
python3 generate_assets.py --count 5000 --seed 20261113 --out data/library
python3 strip_exif.py --check data/library
bash run.sh # the full local reference run
run.sh is the verified reference: it starts the Worker locally, seeds the
emulated R2 bucket, tags through the gate, proves the gate refuses a bad
record, reconciles the budget, verifies the evidence and writes a sanitized
log. The learner still types each command from COMMANDS.md and observes it.
Files
| File | Purpose |
|---|---|
governance-rule.json |
The S8 six-part rule plus tag_schema and ingest; the single source the Worker and pipeline both read |
generate_assets.py |
Seeded 5,000-asset generator: catalogue, 400 px PNGs, labels, 200-asset holdout, hashes |
tag.py |
Preflight, batches of 100, checkpoint/resume, local validation, Worker post, failure log, monthly batch, review sample |
reconcile.py |
Reconciles actuals against the $80 spine and the $5/$10 envelopes |
reconcile.ipynb |
The same reconciliation as a notebook |
budget.csv |
The monthly spine and the capstone's actual lines, with a basis and note per line |
strip_exif.py |
Checks or strips EXIF before an image leaves the laptop |
scripts/sanitize_log.py |
Removes tokens, account IDs, emails and keys from a log |
src/index.js |
The S4 Worker extended with POST /ingest/tags and rule validation |
test/worker.test.js |
14 Worker tests, including the gate's refusals |
tests/test_capstone.py |
18 Python tests for the generator, pipeline, budget, EXIF and sanitizer |
compose.yaml, Caddyfile, .env.example |
The S5 Nextcloud/MariaDB/Redis/Caddy NAS stack |
compose.local.yaml |
The laptop fallback stack on port 8080 |
up.sh, down.sh |
Open and close the bounded 72-hour window; write the teardown log |
run.sh |
The verified reference runner |
verify.sh |
The machine proof over the evidence bundle |
COMMANDS.md |
Every command with an explanation |
The ten-item evidence bundle
- The generated manifest: seed, count, generator hash, catalogue hash.
- The tag output (
tags.jsonl,report.json): schema validity, coverage, and every failed asset infailures.jsonl. - Worker proof:
/health,/asset/:idwith tags,/assets?tag=<tag>, the refused record and the accepted governed write. - Governance: the rule file, the dated endpoint snapshot, the refused and accepted OpenRouter requests, and the 10% sample-review sheet.
- NAS proof: RAID1 status, originals in Nextcloud, the
rclonebackup and the restore checksum. - One measured 40-item monthly batch and its run-rate projection.
- Cost actuals: OpenRouter usage, the DigitalOcean balance and bill, R2 usage, reconciled against $5 and $80; no-auto-top-up proof.
- The budget sheet: forecast versus actuals, with every delta explained.
- The sanitized command log,
COMMANDS.mdand your runner. - The teardown log and the final balance, with the no-resources-running check.
Budget
| Line | Monthly spine | Capstone actual | Why |
|---|---|---|---|
| Storage | $25 | ≈ $0.20 | 20 GiB of block storage for 72 hours; R2 stays in the free tier |
| Compute and CDN | $25 | ≈ $2.36 | one s-2vcpu-4gb Droplet for 72 hours; Workers and CDN are free |
| Egress | $15 | $0.00 | R2 egress is free |
| Inference | $5 | measured | the 40-item monthly batch projected to 40/month |
| Buffer | $10 | $10.00 | held, not spent |
| Total | $80 | ≈ $12.56 + inference | the bounded window, not a month of Droplet |
The $12.56 is the envelope, including the $10 the buffer holds back; cash spend
is about $2.56 plus the measured inference line. budget-reconciliation.json
reports both actual_total_usd and spent_usd so the distinction is explicit.
The one-off backfill is capped at the $10 OpenRouter credit carried from S8,
separately from the monthly line. python3 reconcile.py --check exits non-zero
if inference exceeds $5, the total exceeds $80, or the backfill exceeds $10.
Governance
governance-rule.json is the S8 rule extended for the capstone:
- Part 1: synthetic/public/internal data only; real personal or sensitive media never leaves the laptop.
- Part 2: names, emails, phones, student IDs, GPS, device and timestamp
metadata are removed before any request (
strip_exif.pychecks images). - Part 3: the endpoint must satisfy the rule —
zdr: true,data_collection: "deny",allow_fallbacks: false— and the pipeline refuses to start if the dated snapshot has no qualifying endpoint. - Part 4–5: no in-region route on the student plan; nothing retained.
- Part 6: a 10% sample is reviewed; exceptions are approved in writing.
The Worker's ingest route validates every record against tag_schema and
ingest and writes nothing if any record fails. The refused and accepted pair
in data/run/govern-pair.json is the evidence, not an assertion.
The 72-hour window
Cloud resources run in a bounded window: up.sh opens it (and refuses a second
window while one is live), down.sh closes it, and both write timestamps to
data/run/teardown.log. The window is why the compute and storage lines are
window costs, not a month's Droplet. Deleting the Droplet does not delete its
volumes; deleting an R2 bucket does not remove a DNS record. COMMANDS.md
section K lists both checks.
Fallback chain
Every fallback keeps the evidence shape and earns full points when labelled:
workers.dev + r2.dev; the instructor demo bucket + wrangler dev --local;
compose.local.yaml for the NAS; a free-tier or instructor OpenRouter key; the
classifier on MPS/CPU. A fallback that changes the evidence shape is a defect.
Safety
Synthetic media only. No real people, client footage, brands or personal data.
Never commit .env, .dev.vars or a token; chmod 600 both. Sanitize the log
before publishing it. The generated labels are the generator's ground truth and
must not be read by a managed pipeline; the canned stub reads them and is
labelled canned in the report.