reactbin/specs/001-reaction-image-board/tasks.md

description

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)

# 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