10 KiB
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.