163 lines
10 KiB
Markdown
163 lines
10 KiB
Markdown
# Task Breakdown: Anonymous Desire Aggregator
|
|
|
|
**Feature**: Anonymous Desire Aggregator
|
|
**Date**: 2025-10-09
|
|
|
|
This document breaks down the implementation of the feature into actionable, dependency-ordered tasks.
|
|
|
|
## Implementation Strategy
|
|
|
|
The feature will be developed in phases, aligned with user stories. Each phase represents an independently testable and deliverable increment of functionality. The MVP (Minimum Viable Product) is the completion of User Story 1, which allows a user to create a session.
|
|
|
|
**Note on TDD**: All new features and bug fixes MUST follow a Test-Driven Development approach. This means tests should be written first, observed to fail, and then made to pass upon completion of the implementation.
|
|
|
|
---
|
|
|
|
## Phase 1: Project Setup
|
|
|
|
**Goal**: Initialize the frontend and backend projects and set up the Docker environment.
|
|
|
|
| ID | Task | Files / Location | Status |
|
|
|---|---|---|---|
|
|
| T001 | [P] Initialize the `frontend` project using Create React App with the TypeScript template. | `frontend/` | Done |
|
|
| T002 | [P] Initialize the `backend` Node.js project (`npm init`) and set up TypeScript. | `backend/` | Done |
|
|
| T003 | [P] Create a basic `Dockerfile` for the `frontend` service. | `frontend/Dockerfile` | Done |
|
|
| T004 | [P] Create a basic `Dockerfile` for the `backend` service. | `backend/Dockerfile` | Done |
|
|
| T005 | Create the `docker-compose.yaml` file to orchestrate the frontend and backend services. | `docker-compose.yaml` | Done |
|
|
| T005.5 | Define and review the `openapi.yaml` API contract. | `specs/001-people-tend-to/contracts/openapi.yaml` | Done |
|
|
| T006 | Install core dependencies for the `backend`: express, ws, typescript, @google/generative-ai. | `backend/package.json` | Done |
|
|
| T007 | Install core dependencies for the `frontend`: react, react-dom, @mui/material, @emotion/react. | `frontend/package.json` | Done |
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational Tasks
|
|
|
|
**Goal**: Implement core services and hooks that are prerequisites for all user stories.
|
|
|
|
| ID | Task | Files / Location | Status |
|
|
|---|---|---|---|
|
|
| T008 | [Backend] Implement the basic WebSocket server to handle connections and manage a list of clients. | `backend/src/ws/` | Done |
|
|
| T009 | [Frontend] [P] Implement a `WebSocketService` to connect to the backend and handle incoming/outgoing messages. | `frontend/src/services/` | Done |
|
|
| T010 | [Frontend] [P] Implement a `useSession` custom hook to manage the session state in Local Storage. | `frontend/src/hooks/` | Done |
|
|
| T011 | [Frontend] Set up the basic Material-UI theme and provider. | `frontend/src/App.tsx` | Done |
|
|
|
|
---
|
|
|
|
## Phase 3: [US1] Create and Share a Session
|
|
|
|
**Goal**: A user can create a new session and get a shareable link.
|
|
**Independent Test**: Can be verified by calling the `/sessions` endpoint and seeing a valid session ID returned, then loading the frontend at that URL.
|
|
|
|
| ID | Task | Files / Location | Status |
|
|
|---|---|---|---|
|
|
| T012 | [Backend] Write a test for the `POST /sessions` endpoint. | `backend/tests/` | Done |
|
|
| T013 | [Backend] Implement the `POST /sessions` endpoint to generate and return a unique session ID. | `backend/src/routes/` | Done |
|
|
| T014 | [Frontend] [P] Write a test for the `CreateSession` page component. | `frontend/src/pages/` | Done |
|
|
| T015 | [Frontend] [P] Create the UI component for the session creation form (topic, participant count). | `frontend/src/pages/` | Done |
|
|
| T016 | [Frontend] Implement the client-side logic to call the `POST /sessions` API. | `frontend/src/pages/` | Done |
|
|
| T017 | [Frontend] On successful session creation, initialize the `Session` object in Local Storage via the `useSession` hook and redirect to the new session URL. | `frontend/src/pages/` | Done |
|
|
|
|
**Checkpoint**: User Story 1 is complete and independently testable. MVP is met.
|
|
|
|
---
|
|
|
|
## Phase 4: [US2] Participate in a Session
|
|
|
|
**Goal**: A user can join a session, see its status, and submit their desires.
|
|
**Independent Test**: Can be verified by multiple clients connecting to the same session URL, submitting forms, and seeing the participant count update.
|
|
|
|
| ID | Task | Files / Location | Status |
|
|
|---|---|---|---|
|
|
| T018 | [Backend] Implement WebSocket logic to relay `SHARE_STATE` and `SUBMIT_DESIRES` messages to all clients in a session. | `backend/src/ws/` | Done |
|
|
| T019 | [Frontend] [P] Write a test for the `DesireForm` component. | `frontend/src/components/` | Done |
|
|
| T020 | [Frontend] [P] Create the UI component for the desire submission form (Want, Accept, NoGoes). | `frontend/src/components/` | Done |
|
|
| T020.1 | [Frontend] Implement validation to prevent empty desire submissions (FR-020). | `frontend/src/components/` | Done |
|
|
| T020.2 | [Frontend] Implement validation to prevent conflicting categories in submissions (FR-016). | `frontend/src/components/` | Done |
|
|
| T020.3 | [Frontend] Implement logic to prevent resubmission from the same client (FR-017). | `frontend/src/hooks/useSession.ts` | Done |
|
|
| T021 | [Frontend] Implement logic to send the `SUBMIT_DESIRES` message via WebSocket. | `frontend/src/pages/` | Done |
|
|
| T022 | [Frontend] Implement logic to handle incoming `STATE_UPDATE` messages and update the local session state. | `frontend/src/hooks/useSession.ts` | Done |
|
|
| T023 | Create a UI component to display the "Waiting for X more participants..." status. | `frontend/src/components/` | Done |
|
|
| T023.1 | [Backend] Implement session locking logic when expected participants are reached. | `backend/src/ws/` | Done |
|
|
| T023.2 | [Frontend] Implement UI to disable submission form and display "Session Full" / "Analysis in Progress" message. | `frontend/src/components/` | Done |
|
|
|
|
**Checkpoint**: User Story 2 is complete and independently testable.
|
|
|
|
---
|
|
|
|
## Phase 5: [US3] View Aggregated Results
|
|
|
|
**Goal**: Users can see the final, categorized results of the session.
|
|
**Independent Test**: Can be verified by having the creator client trigger the analysis and all clients seeing the same results displayed.
|
|
|
|
| ID | Task | Files / Location | Status |
|
|
|---|---|---|---|
|
|
| T024 | [Backend] [P] Write a test for the `LLMService`, mocking the Gemini API client. | `backend/tests/` | Done |
|
|
| T024.1 | [Backend] Write comprehensive automated test cases for the aggregation logic (SC-004). | `backend/tests/` | Done |
|
|
| T025 | [Backend] [P] Implement the `LLMService` to construct the prompt and call the Gemini API. | `backend/src/services/` | Done |
|
|
| T026 | [Backend] Write a test for the `POST /sessions/{sessionId}/analyze` endpoint. | `backend/tests/` | Done |
|
|
| T027 | [Backend] Implement the `POST /sessions/{sessionId}/analyze` endpoint. | `backend/src/routes/` | Done |
|
|
| T028 | [Backend] Implement the WebSocket broadcast for the `ANALYSIS_COMPLETE` message. | `backend/src/ws/` | Done |
|
|
| T029 | [Frontend] [P] Write a test for the `ResultsDisplay` component. | `frontend/src/components/` | Done |
|
|
| T030 | [Frontend] [P] Create UI components for displaying the `GoTos`, `AlsoGoods`, `Considerable`, and `NoGoes` categories. | `frontend/src/components/` | Done |
|
|
| T031 | [Frontend] Implement the UI logic to collapse the "Considerable" category by default. | `frontend/src/components/` | Done |
|
|
| T032 | [Frontend] Implement the logic for the creator's client to call the `analyze` endpoint. | `frontend/src/pages/` | Done |
|
|
| T033 | [Frontend] Implement the handler for the `ANALYSIS_COMPLETE` message to update the UI. | `frontend/src/hooks/useSession.ts` | Done |
|
|
| T033.1 | [Frontend] Ensure real-time synchronization of the results view (FR-015). | `frontend/src/pages/` | Done |
|
|
|
|
**Checkpoint**: User Story 3 is complete and independently testable.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Integration
|
|
|
|
**Goal**: Finalize the application with error handling, loading states, and end-to-end testing.
|
|
|
|
| ID | Task | Files / Location | Status |
|
|
|---|---|---|---|
|
|
| T034 | [Frontend] Add loading indicators for API calls and WebSocket events. | `frontend/src/components/` | Done |
|
|
| T035 | [Frontend] Add user-friendly error messages for API failures or WebSocket disconnections. | `frontend/src/components/` | Done |
|
|
| T036 | [Docs] Write end-to-end test plan for manual execution. | `tests/e2e.md` | Done |
|
|
| T036.5 | [Docs] Plan and conduct user satisfaction surveys to measure SC-005. | `docs/user-satisfaction.md` | Done |
|
|
|
|
---
|
|
|
|
## Phase 7: Performance & Scalability
|
|
|
|
**Goal**: Optimize application performance and ensure scalability.
|
|
|
|
| ID | Task | Files / Location | Status |
|
|
|---|---|---|---|
|
|
| T037 | [Backend] Implement caching for LLM responses to reduce latency and API calls. | `backend/src/services/LLMService.ts` | Done |
|
|
| T038 | [Backend] Implement load testing for the WebSocket server to ensure it handles concurrent connections. | `backend/tests/` | Done |
|
|
| T039 | [Frontend] Optimize React component rendering to minimize re-renders. | `frontend/src/components/`, `frontend/src/pages/` | Done |
|
|
| T040 | [Docs] Document performance testing results against SC-001 and SC-003. | `docs/performance.md` | Done |
|
|
|
|
---
|
|
|
|
## Phase 8: Security & Privacy
|
|
|
|
**Goal**: Ensure the application adheres to privacy mandates and security best practices.
|
|
|
|
| ID | Task | Files / Location | Status |
|
|
|---|---|---|---|
|
|
| T041 | [Backend] Implement strict logging policies to ensure no user desire content is persisted. | `backend/src/` | Done |
|
|
| T042 | [Backend] Review LLM API calls to confirm only necessary data is sent and no PII is exposed. | `backend/src/services/LLMService.ts` | Done |
|
|
| T043 | [Frontend] Implement measures to prevent accidental exposure of session IDs or participant data. | `frontend/src/` | Done |
|
|
| T044 | [Docs] Document privacy compliance measures. | `docs/privacy.md` | Done |
|
|
|
|
---
|
|
|
|
## Phase 9: Session Management & Cleanup
|
|
|
|
**Goal**: Implement session lifecycle management, including termination and expiration handling.
|
|
|
|
| ID | Task | Files / Location | Status |
|
|
|---|---|---|---|
|
|
| T045 | [Backend] Implement session termination logic (e.g., timeout mechanism for inactive sessions). | `backend/src/ws/` | Done |
|
|
| T046 | [Frontend] Implement "Session Expired" message and redirection to home page. | `frontend/src/pages/` | Done |
|
|
|
|
## Dependencies
|
|
|
|
- **User Story Completion Order**: US1 → US2 → US3
|
|
- **Parallel Work**: Within each user story phase, frontend and backend tasks marked with `[P]` can often be worked on in parallel, but frontend component implementation depends on the tests being written first.
|