[Spec Kit] Initial commit — constitution, spec, plan, and tasks for Reaction Image Board v1

2026-05-02 15:56:39 +00:00
commit 691f7570fe
46 changed files with 6149 additions and 0 deletions
--- a/specs/001-reaction-image-board/tasks.md
+++ b/specs/001-reaction-image-board/tasks.md
@@ -0,0 +1,352 @@
+---
+
+description: "Task list for Reaction Image Board v1"
+---
+
+# Tasks: Reaction Image Board v1
+
+**Input**: Design documents from `specs/001-reaction-image-board/`
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, data-model.md ✅, contracts/api.md ✅
+
+**Tests**: Per §5.1 of the constitution, TDD is non-negotiable. Test tasks
+MUST appear before every implementation task. Write the test, confirm it
+fails, then implement until it passes.
+
+**Organization**: Tasks follow the milestone order from plan.md (API-first,
+serial). Each task is tagged with the user story it serves.
+
+## Format: `[ID] [P?] [Story?] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies on incomplete tasks)
+- **[Story]**: Which user story this task serves (US1–US5 per spec.md)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+```
+api/app/              API source
+api/tests/unit/       API unit tests
+api/tests/integration/ API integration tests
+api/alembic/versions/ Database migrations
+ui/src/app/           Angular source
+ui/src/app/services/  Angular services (+ .spec.ts colocated)
+ui/src/app/<feature>/ Angular component dirs (+ .spec.ts colocated)
+```
+
+---
+
+## Phase 1: Setup (Project Skeleton — M0)
+
+**Purpose**: Establish the monorepo layout, Docker Compose stack, and linting
+baseline. No feature logic. All subsequent milestones build on this.
+
+- [ ] T001 Create top-level monorepo layout: `api/`, `ui/`, `docker-compose.yml`, `.env.example`
+- [ ] T002 Write `.env.example` with all variables from spec §5 (DATABASE_URL, S3_*, API_BASE_URL, MAX_UPLOAD_BYTES)
+- [ ] T003 [P] Write `api/Dockerfile` (Python 3.12 slim, installs pyproject.toml deps, runs uvicorn)
+- [ ] T004 [P] Scaffold Angular project with CLI into `ui/` (strict mode, standalone components, routing)
+- [ ] T005 [P] Write `ui/Dockerfile` (Node LTS, `ng serve --host 0.0.0.0`)
+- [ ] T006 Write `docker-compose.yml` defining: postgres, minio, api (depends_on postgres+minio), ui (depends_on api)
+- [ ] T007 [P] Configure `api/pyproject.toml` with FastAPI, SQLAlchemy 2.x async, asyncpg, Alembic, aiobotocore, pydantic-settings, pytest, pytest-asyncio, ruff
+- [ ] T008 [P] Configure `ui/package.json` / `angular.json` with eslint + prettier; add `ui/proxy.conf.json` routing `/api/*` to `http://localhost:8000`
+- [ ] T009 Write API unit test: settings load from env vars without error in `api/tests/unit/test_config.py`
+- [ ] T010 Write API integration test: `GET /api/v1/health` returns 200 `{"status":"ok"}` in `api/tests/integration/test_health.py`
+- [ ] T011 Implement `api/app/config.py` (pydantic-settings reading all env vars)
+- [ ] T012 Implement `api/app/main.py` (FastAPI factory, lifespan connecting to Postgres + MinIO, health route)
+- [ ] T013 Configure Alembic in `api/alembic/` with async engine; apply `alembic upgrade head` on startup
+- [ ] T014 [P] Add Angular default smoke test in `ui/src/app/app.component.spec.ts`
+
+**Checkpoint**: `docker compose up` starts all four services. Health endpoint
+returns 200. Both linters pass. All tests pass.
+
+---
+
+## Phase 2: Foundational (Upload API Infrastructure — M1 core)
+
+**Purpose**: Core interfaces and repositories that MUST exist before any user
+story endpoint can be implemented. Establishes the `StorageBackend`,
+`AuthProvider`, and `ImageRepository` abstractions.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
+
+- [ ] T015 Write unit test: SHA-256 hash of known bytes returns expected hex digest in `api/tests/unit/test_hashing.py`
+- [ ] T016 Write unit test: MIME validator accepts jpeg/png/gif/webp and rejects pdf/mp4 in `api/tests/unit/test_validation.py`
+- [ ] T017 Write unit test: file size validator rejects bytes exceeding MAX_UPLOAD_BYTES in `api/tests/unit/test_validation.py`
+- [ ] T018 [P] Implement `StorageBackend` interface (put, get_presigned_url, delete) in `api/app/storage/backend.py`
+- [ ] T019 [P] Implement `S3StorageBackend` using aiobotocore in `api/app/storage/s3_backend.py`
+- [ ] T020 [P] Implement `AuthProvider` interface + `NoOpAuthProvider` in `api/app/auth/provider.py` and `api/app/auth/noop.py`
+- [ ] T021 Implement MIME type + file size validation helpers in `api/app/routers/images.py` (or `api/app/validation.py`)
+- [ ] T022 Write Alembic migration for `images` table in `api/alembic/versions/`
+- [ ] T023 Implement `Image` SQLAlchemy model in `api/app/models.py`
+- [ ] T024 Implement `ImageRepository` (create, get_by_id, get_by_hash) in `api/app/repositories/image_repo.py`
+- [ ] T025 Wire `AuthProvider`, `StorageBackend`, and DB session into FastAPI dependency injection in `api/app/dependencies.py`
+
+**Checkpoint**: All unit tests pass; foundation ready for user story endpoints.
+
+---
+
+## Phase 3: User Story 1 — Upload an Image (M1 endpoint + M5 UI) 🎯 MVP
+
+**Goal**: A user can upload an image (with tags, though tag persistence is
+deferred to Phase 4). Duplicate detection works. Errors shown inline.
+
+**Independent Test**: Upload a JPEG via the UI, verify it appears in the
+library grid. Re-upload the same file, verify "Already in your library" toast
+and no duplicate in DB or MinIO.
+
+### Tests for User Story 1 (REQUIRED per §5.1 — TDD) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T026 [P] [US1] Integration test: valid JPEG upload → 201, record in DB, object in MinIO in `api/tests/integration/test_upload.py`
+- [ ] T027 [P] [US1] Integration test: same image uploaded twice → 200, `duplicate: true`, no second MinIO object in `api/tests/integration/test_upload.py`
+- [ ] T028 [P] [US1] Integration test: invalid MIME type → 422 with `{"detail":"...","code":"invalid_mime_type"}` in `api/tests/integration/test_upload.py`
+- [ ] T029 [P] [US1] Integration test: file > MAX_UPLOAD_BYTES → 422 `file_too_large` in `api/tests/integration/test_upload.py`
+- [ ] T030 [P] [US1] Angular unit test: tag chip input lowercases and splits on comma/space in `ui/src/app/upload/upload.component.spec.ts`
+- [ ] T031 [P] [US1] Angular unit test: `duplicate: true` response → toast shown, navigate to detail in `ui/src/app/upload/upload.component.spec.ts`
+- [ ] T032 [P] [US1] Angular unit test: `duplicate: false` response → success toast, navigate to detail in `ui/src/app/upload/upload.component.spec.ts`
+- [ ] T033 [P] [US1] Angular unit test: error response → inline error shown, no navigation in `ui/src/app/upload/upload.component.spec.ts`
+
+### Implementation for User Story 1
+
+- [ ] T034 [US1] Implement `POST /api/v1/images` endpoint (MIME check, size check, SHA-256, duplicate query, storage write, record insert; tags field accepted but ignored) in `api/app/routers/images.py`
+- [ ] T035 [US1] Implement `ImageService` wrapping `GET /api/v1/images` and `GET /api/v1/images/{id}/file` in `ui/src/app/services/image.service.ts`
+- [ ] T036 [US1] Implement `UploadComponent` (route `/upload`) with drag-and-drop zone, click-to-browse, tag chip input, POST submit, duplicate/success/error handling in `ui/src/app/upload/upload.component.ts`
+
+**Checkpoint**: Full upload flow works in browser. Duplicate detection gives
+correct feedback. API tests and Angular unit tests all pass.
+
+---
+
+## Phase 4: User Story 2 — Browse and Filter the Library (M2 list/search + M4 UI)
+
+**Goal**: User can view all images in a responsive grid and filter by one or
+more tags (AND logic). Pagination works. Tags are persisted during upload.
+
+**Independent Test**: Seed the library via the upload flow. Apply a single tag
+filter and verify only matching images are shown. Add a second filter, verify
+both tags must be present. Remove a filter, verify the grid expands.
+
+### Tests for User Story 2 (REQUIRED per §5.1 — TDD) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T037 [P] [US2] Unit test: tag normalisation — uppercase → lowercase, whitespace stripped in `api/tests/unit/test_tags.py`
+- [ ] T038 [P] [US2] Unit test: tag validation — rejects names > 64 chars, invalid chars in `api/tests/unit/test_tags.py`
+- [ ] T039 [P] [US2] Integration test: upload with tags → tags persisted, returned in response in `api/tests/integration/test_tags.py`
+- [ ] T040 [P] [US2] Integration test: duplicate upload → existing record returned, tags unchanged in `api/tests/integration/test_tags.py`
+- [ ] T041 [P] [US2] Integration test: `GET /api/v1/images?tags=cat,funny` → only images with both tags in `api/tests/integration/test_search.py`
+- [ ] T042 [P] [US2] Integration test: same query excludes images with only one matching tag in `api/tests/integration/test_search.py`
+- [ ] T043 [P] [US2] Angular unit test: `ImageService` constructs correct query params from filter state in `ui/src/app/services/image.service.spec.ts`
+- [ ] T044 [P] [US2] Angular unit test: `LibraryComponent` renders image grid from mocked service in `ui/src/app/library/library.component.spec.ts`
+- [ ] T045 [P] [US2] Angular unit test: filter change triggers new API call with updated `tags` param in `ui/src/app/library/library.component.spec.ts`
+
+### Implementation for User Story 2
+
+- [ ] T046 [US2] Write Alembic migration for `tags` and `image_tags` tables in `api/alembic/versions/`
+- [ ] T047 [US2] Implement `Tag` and `ImageTag` SQLAlchemy models in `api/app/models.py`
+- [ ] T048 [US2] Implement tag normalisation + validation helpers in `api/app/repositories/tag_repo.py`
+- [ ] T049 [US2] Implement `TagRepository` (upsert_by_name, get_by_image_id) in `api/app/repositories/tag_repo.py`
+- [ ] T050 [US2] Update `POST /api/v1/images` to process and persist the `tags` field in `api/app/routers/images.py`
+- [ ] T051 [US2] Implement `GET /api/v1/images` with `tags` (AND-filter), `limit`, `offset` in `api/app/routers/images.py`
+- [ ] T052 [US2] Implement `GET /api/v1/images/{id}` returning image + tags in `api/app/routers/images.py`
+- [ ] T053 [US2] Update `ImageService` to support `tags` filter query param in `ui/src/app/services/image.service.ts`
+- [ ] T054 [US2] Implement `LibraryComponent` (route `/`) with image grid, tag chips, debounced filter bar, "Load more" pagination in `ui/src/app/library/library.component.ts`
+
+**Checkpoint**: Library view shows real images with tags. Tag filtering (AND
+logic) and pagination work end-to-end.
+
+---
+
+## Phase 5: User Story 3 — View Image Detail and Edit Tags (M3 serving + M6 detail UI)
+
+**Goal**: User can view a full-size image and edit its tags inline. Changes
+saved on blur/Enter.
+
+**Independent Test**: Open an image detail page, add a new tag, navigate back,
+filter by that tag, and confirm the image appears.
+
+### Tests for User Story 3 (REQUIRED per §5.1 — TDD) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T055 [P] [US3] Integration test: `GET /api/v1/images/{id}/file` → 302 with `Location` header pointing to MinIO URL in `api/tests/integration/test_serving.py`
+- [ ] T056 [P] [US3] Integration test: `/file` for unknown ID → 404 `image_not_found` in `api/tests/integration/test_serving.py`
+- [ ] T057 [P] [US3] Integration test: `PATCH /api/v1/images/{id}/tags` replaces tags, old tags unlinked, new tags upserted in `api/tests/integration/test_tags.py`
+- [ ] T058 [P] [US3] Integration test: PATCH with invalid tag → 422 `invalid_tag` in `api/tests/integration/test_tags.py`
+- [ ] T059 [P] [US3] Angular unit test: removing tag chip calls PATCH with updated list (removed tag absent) in `ui/src/app/detail/detail.component.spec.ts`
+- [ ] T060 [P] [US3] Angular unit test: adding tag + Enter calls PATCH with new tag included in `ui/src/app/detail/detail.component.spec.ts`
+
+### Implementation for User Story 3
+
+- [ ] T061 [US3] Implement `GET /api/v1/images/{id}/file` (generate 1-hour pre-signed URL, return 302) in `api/app/routers/images.py`
+- [ ] T062 [US3] Implement `TagRepository.replace_tags_on_image` in `api/app/repositories/tag_repo.py`
+- [ ] T063 [US3] Implement `PATCH /api/v1/images/{id}/tags` in `api/app/routers/images.py`
+- [ ] T064 [US3] Implement `DetailComponent` (route `/images/:id`) with full-size image, editable tag chips (add/remove), save on blur/Enter via PATCH, back button in `ui/src/app/detail/detail.component.ts`
+
+**Checkpoint**: Full-size image loads in browser via redirect. Tag editing
+works from detail page. Changes persist across page navigation.
+
+---
+
+## Phase 6: User Story 4 — Delete an Image (M6 detail UI + M2 delete endpoint)
+
+**Goal**: User can permanently delete an image with confirmation. Returns to
+library afterwards.
+
+**Independent Test**: Delete a known image, confirm it no longer appears in the
+library and that navigating to its former URL shows a not-found screen.
+
+### Tests for User Story 4 (REQUIRED per §5.1 — TDD) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T065 [P] [US4] Integration test: `DELETE /api/v1/images/{id}` → 204; subsequent `GET /{id}` returns 404 in `api/tests/integration/test_delete.py`
+- [ ] T066 [P] [US4] Integration test: DELETE verifies MinIO object is removed in `api/tests/integration/test_delete.py`
+- [ ] T067 [P] [US4] Integration test: DELETE of unknown ID → 404 `image_not_found` in `api/tests/integration/test_delete.py`
+- [ ] T068 [P] [US4] Angular unit test: delete confirmation → DELETE called → navigation to Library in `ui/src/app/detail/detail.component.spec.ts`
+- [ ] T069 [P] [US4] Angular unit test: cancel confirmation dialog → no DELETE call, stays on detail page in `ui/src/app/detail/detail.component.spec.ts`
+
+### Implementation for User Story 4
+
+- [ ] T070 [US4] Implement `DELETE /api/v1/images/{id}` (delete image_tags rows, image record, S3 object) in `api/app/routers/images.py`
+- [ ] T071 [US4] Add delete button with confirmation dialog + back-to-Library navigation to `DetailComponent` in `ui/src/app/detail/detail.component.ts`
+- [ ] T072 [US4] Implement `NotFoundComponent` shown for all unrecognised routes in `ui/src/app/not-found/not-found.component.ts`
+
+**Checkpoint**: Full CRUD loop works: upload → view → re-tag → delete.
+Deleted images gone from library and storage.
+
+---
+
+## Phase 7: User Story 5 — Browse and Search Tags (M2 tags endpoint + UI)
+
+**Goal**: User can list all tags alphabetically with image counts and narrow
+by prefix.
+
+**Independent Test**: Open the tag browser, verify every tag present in the
+library appears with a correct image count. Type a prefix and verify only
+matching tags remain.
+
+### Tests for User Story 5 (REQUIRED per §5.1 — TDD) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T073 [P] [US5] Integration test: `GET /api/v1/tags` returns all tags alphabetically with correct image_count in `api/tests/integration/test_tags.py`
+- [ ] T074 [P] [US5] Integration test: `GET /api/v1/tags?q=ca` returns only tags prefixed "ca" in `api/tests/integration/test_tags.py`
+- [ ] T075 [P] [US5] Angular unit test: `TagService` calls `GET /api/v1/tags` with `q` param in `ui/src/app/services/tag.service.spec.ts`
+
+### Implementation for User Story 5
+
+- [ ] T076 [US5] Implement `GET /api/v1/tags` with `q` prefix search, `limit`, `offset`, image_count in `api/app/routers/tags.py`
+- [ ] T077 [US5] Implement `TagService` wrapping `GET /api/v1/tags` in `ui/src/app/services/tag.service.ts`
+- [ ] T078 [US5] Wire `TagService` into `LibraryComponent` tag filter bar for tag autocomplete/selection in `ui/src/app/library/library.component.ts`
+
+**Checkpoint**: All user stories independently functional and tested.
+
+---
+
+## Phase 8: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements affecting multiple user stories and final validation.
+
+- [ ] T079 [P] Add `GET /api/v1/images/{id}` 404 test to verify error envelope shape `{"detail":"...","code":"image_not_found"}` in `api/tests/integration/test_upload.py`
+- [ ] T080 [P] Verify all API error responses include both `detail` and `code` fields (constitution §3.3) — check tests for T028, T029, T056, T058, T067
+- [ ] T081 [P] Add empty-state UI for library with zero images in `ui/src/app/library/library.component.ts`
+- [ ] T082 [P] Add empty-state UI for tag filter returning zero results in `ui/src/app/library/library.component.ts`
+- [ ] T083 Configure Angular routing to show `NotFoundComponent` for all unrecognised routes in `ui/src/app/app.routes.ts`
+- [ ] T084 [P] Run quickstart.md validation: `docker compose up`, upload an image, filter by tag, edit tag, delete image — full happy path
+- [ ] T085 [P] Run `ruff check .` in `api/` — confirm zero lint errors
+- [ ] T086 [P] Run `npm run lint` in `ui/` — confirm zero lint errors
+- [ ] T087 Run all API tests: `docker compose run --rm api pytest` — confirm all pass
+- [ ] T088 Run all UI tests: `docker compose run --rm ui ng test --watch=false` — confirm all pass
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1 (Setup)**: No dependencies — start immediately
+- **Phase 2 (Foundational)**: Depends on Phase 1 — BLOCKS all user stories
+- **Phase 3 (US1 Upload)**: Depends on Phase 2 — API endpoint + Angular upload UI
+- **Phase 4 (US2 Browse)**: Depends on Phase 3 (tags API needs upload first)
+- **Phase 5 (US3 Detail/Edit)**: Depends on Phase 4 (detail view needs list view navigation)
+- **Phase 6 (US4 Delete)**: Depends on Phase 5 (delete is in the detail component)
+- **Phase 7 (US5 Tags)**: Can start after Phase 4 (tag endpoint is independent)
+- **Phase 8 (Polish)**: Depends on all prior phases
+
+### User Story Dependencies
+
+- **US1 (Upload)**: Foundational complete → API endpoint first, then Angular component
+- **US2 (Browse)**: US1 must exist to seed data; tag schema (Phase 4) needed
+- **US3 (View/Edit)**: US2 complete (library navigation leads to detail)
+- **US4 (Delete)**: US3 complete (delete is on the detail view)
+- **US5 (Tags)**: Independent after Phase 4 tag endpoint; can start in parallel with US3/US4
+
+### Within Each Phase
+
+- Test tasks MUST be written and confirmed FAILING before implementation
+- Models before repositories before endpoints
+- API endpoint before Angular service
+- Angular service before Angular component
+- Story complete before moving to next phase
+
+### Parallel Opportunities
+
+- All Phase 1 tasks marked [P] can run in parallel after T001/T002
+- T018–T020 (interfaces) can run in parallel
+- All integration tests within a phase marked [P] can be written in parallel
+- Angular unit tests within a phase marked [P] can be written in parallel
+- T085/T086/T087/T088 (lint + test runs) can run in parallel
+
+---
+
+## Parallel Example: Phase 3 (User Story 1)
+
+```bash
+# Write all tests for US1 in parallel (all different files):
+T026: api/tests/integration/test_upload.py (new upload)
+T027: api/tests/integration/test_upload.py (duplicate)
+T028: api/tests/integration/test_upload.py (invalid MIME)
+T029: api/tests/integration/test_upload.py (oversized)
+T030: ui/src/app/upload/upload.component.spec.ts (tag chips)
+T031: ui/src/app/upload/upload.component.spec.ts (duplicate response)
+
+# Then implement sequentially:
+T034: POST /api/v1/images endpoint
+T035: Angular ImageService
+T036: Angular UploadComponent
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Stories 1 + 2 only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational — BLOCKS all stories
+3. Complete Phase 3: US1 Upload
+4. Complete Phase 4: US2 Browse/Filter
+5. **STOP and VALIDATE**: Upload via UI, filter by tag, verify end-to-end
+6. Can demo at this point: full read+write loop without detail view
+
+### Incremental Delivery
+
+1. Phase 1 + 2 → Foundation ready
+2. Phase 3 → US1 Upload works (MVP start)
+3. Phase 4 → US2 Browse + tag filtering works (MVP complete)
+4. Phase 5 → US3 Detail + tag editing
+5. Phase 6 → US4 Delete (completes full CRUD)
+6. Phase 7 → US5 Tag browser (supplementary)
+7. Phase 8 → Polish + final validation
+
+---
+
+## Notes
+
+- [P] = different files, no incomplete dependencies — safe to parallelise
+- [USN] label maps task to user story for traceability
+- TDD is non-negotiable (§5.1): test → fail → implement → pass
+- API tests run against real Postgres + MinIO (no mocks per §5.2)
+- Milestone done-criterion: all tests pass + linter passes
+- `docker compose up` must keep working after every milestone