🏗️ PHASE 1 — FEATURE REQUIREMENT RECONSTRUCTION 🔎 🎯 Feature Definition Primary Goal Allow authenticated users to save products for later viewing. 👤 User Problem Users may find a product they are interested in but may not want to purchase immediately. 🎯 Target Users Authenticated application users. ⚡ Trigger Product Details ↓ Click "Save" 📥 Inputs Authenticated user identity Product ID Save/remove action 📤 Outputs Saved state displayed in UI Saved products list Success/error feedback 📜 Business Rules 1. A user can save a product only once. 2. A user can remove their saved product. 3. Users can only modify their own saved products. 4. Duplicate save requests must not create duplicate records. 5. Product information should continue coming from the existing product source rather than being duplicated into the wishlist record. ✅ Success Criteria User saves product → Product becomes saved → Saved product appears in wishlist ❌ Failure Behavior Unauthenticated request → rejected. Invalid product → rejected/handled according to existing product behavior. Duplicate save → no duplicate record. Server failure → UI shows recoverable error. ⚠️ Edge Cases Product becomes unavailable. Product is deleted. User rapidly clicks Save multiple times. User removes an already-removed product. Same product is saved from multiple UI locations. 🟢 Explicit Requirements Save product. Remove product. View saved products. Authentication requirement. No duplicate records. 🟡 Inferred Requirements Database uniqueness constraint should protect against duplicates. Backend authorization must enforce user ownership. UI should optimistically or synchronously reflect saved state according to existing frontend conventions. ❓ Unresolved Exact product identifier format. Existing product API. Existing user database model. Existing frontend state-management mechanism. --- 👤 PHASE 2 — USER JOURNEY & BEHAVIOR ANALYSIS 🧭 🟢 Success Journey User ↓ Opens Product ↓ Clicks "Save" ↓ Frontend sends product ID ↓ Backend validates authentication ↓ Backend validates product ↓ Database creates relationship ↓ Success response ↓ UI updates saved state 🗑️ Remove Journey Saved Product ↓ User clicks "Remove" ↓ Backend verifies ownership ↓ Relationship removed ↓ UI updates 📋 View Wishlist User ↓ Opens Saved Products ↓ Frontend requests saved products ↓ Backend identifies current user ↓ Database retrieves saved-product relationships ↓ Existing product information is loaded ↓ Products displayed 🔐 Permission-Denied State Logged-out user: Click Save ↓ Authentication check ↓ Request rejected ↓ Prompt user to log in ⏳ Loading State While save/remove request is processing: Save button ↓ Disabled/loading ↓ Request completes This prevents accidental repeated actions. ❌ Error State API failure ↓ Keep previous confirmed state ↓ Show user-friendly error ↓ Allow retry --- 🧩 PHASE 3 — FEATURE SCOPE & BOUNDARY DEFINITION 🎯 🟢 In Scope Save product. Remove saved product. Saved products page/section. Saved-state indicator. Backend APIs. Database relationship. Authentication enforcement. Ownership enforcement. Duplicate prevention. Tests. 🔴 Out of Scope Product recommendations. Product reviews. Product sharing. Price alerts. Wishlist collaboration. Notifications. Product purchasing. Redesign of the product catalog. ♻️ Reusable Functionality Potentially reusable: Existing authentication middleware. Existing product lookup. Existing product-card component. Existing API client. Existing user identity mechanism. These must be verified in the repository before implementation. --- 🏗️ PHASE 4 — ARCHITECTURE IMPACT ANALYSIS 🔧 🖥️ Frontend Potential impact: Product Card Product Details Saved Products Page Saved State API Client ⚙️ Backend Potential impact: Authentication Wishlist/Saved Product Service Product Validation Database Access API Routes 🗄️ Database A relationship between: User ↓ Saved Product ↓ Product is likely required. Proposed model saved_products user_id product_id created_at This is a PROPOSED CHANGE, not a confirmed existing schema. 🔐 Authentication Existing authentication should be reused. 🛡️ Authorization Backend must derive the user identity from trusted authentication context. The client must not be allowed to specify another user's ownership identity. 📊 Observability Potentially track: Save failures. Remove failures. API error rates. Database constraint violations. Exact observability mechanism remains repository-dependent. --- 📁 PHASE 5 — FILE & DIRECTORY IMPACT MAPPING 🗂️ Because exact files were not provided, the following paths are PROPOSED, not confirmed. Action File Status Responsibility MODIFY src/frontend/.../ProductCard... Proposed Add Save action MODIFY src/frontend/.../ProductDetails... Proposed Add Save state/action CREATE src/frontend/.../SavedProducts... Proposed Saved-products UI CREATE src/backend/.../savedProducts... Proposed Business logic CREATE src/backend/.../savedProductsRoutes... Proposed API routes CREATE/MODIFY Existing data-access location Unknown Persistence CREATE Database migration location Proposed Saved-product relationship CREATE Relevant test location Proposed Feature tests 🚨 Coding-Agent Rule Before modifying or creating anything: Inspect repository ↓ Locate existing product components ↓ Locate authentication middleware ↓ Locate product APIs ↓ Locate database models ↓ Locate migration system ↓ Locate test conventions ↓ Only then finalize file paths --- 🎨 PHASE 6 — FRONTEND COMPONENT & STATE ARCHITECTURE 🖥️ Components Product Card Responsibilities: Display saved/unsaved state. Trigger save/remove action. Show loading state. Product Details Responsibilities: Display same saved state. Reuse save functionality where appropriate. Saved Products Responsibilities: Request saved products. Display product cards. Handle loading. Handle empty state. Handle errors. 📊 State Potential state: isSaved isSaving saveError savedProducts loading Exact state-management approach must follow the repository's existing conventions. ♿ Accessibility Save controls should include: Accessible label. Keyboard interaction. Clear saved/unsaved state. Loading state communicated appropriately. --- ⚙️ PHASE 7 — BACKEND & BUSINESS LOGIC ARCHITECTURE 🔧 Proposed Responsibility Separation Route/Controller ↓ Authentication ↓ Validation ↓ Saved Product Service ↓ Repository/Data Access ↓ Database Business Logic Save Validate user ↓ Validate product ↓ Create relationship ↓ Prevent duplicate Remove Validate user ↓ Find relationship belonging to user ↓ Delete relationship List Validate user ↓ Find saved-product relationships ↓ Resolve associated products ↓ Return result Idempotency Save should be safe against repeated requests. The strongest protection should be a database-level uniqueness constraint: UNIQUE(user_id, product_id) if compatible with the existing data model. --- 🔌 PHASE 8 — API & CONTRACT DESIGN 🌐 The following APIs are PROPOSED, not existing APIs. 🆕 API 1 — Save Product POST /api/saved-products Request { "productId": "PRODUCT_ID" } Authentication Required. Authorization User identity comes from authenticated request context. Response { "saved": true, "productId": "PRODUCT_ID" } 🆕 API 2 — Remove Product DELETE /api/saved-products/:productId Authentication Required. Response { "saved": false, "productId": "PRODUCT_ID" } 🆕 API 3 — List Saved Products GET /api/saved-products Authentication Required. Response { "items": [] } Potential Errors 401 → Not authenticated 404 → Product/resource not found where applicable 400 → Invalid request 409 → Conflict where repository convention requires it 500 → Unexpected server error Exact status-code conventions must be aligned with the existing API. --- 🗄️ PHASE 9 — DATABASE & DATA-MODEL IMPACT 💾 Proposed Relationship Users │ │ 1 │ ├──────< SavedProducts >──────┐ │ │ 1 Products Proposed Table saved_products Potential fields: Field Purpose user_id User ownership product_id Saved product created_at Save timestamp Constraints Recommended: PRIMARY/IDENTITY KEY FOREIGN KEY user_id FOREIGN KEY product_id UNIQUE(user_id, product_id) Exact syntax and key strategy must follow the existing database architecture. Indexes Potential index: (user_id) Potential composite uniqueness/index: (user_id, product_id) Migration A database migration would likely be required if no existing saved-product relationship exists. Rollback Rollback should remove the newly introduced relationship structure without modifying existing product records. Backfill Likely none because this is a new user relationship. --- 🔐 PHASE 10 — SECURITY, AUTHORIZATION & DATA PROTECTION 🛡️ Authentication All saved-product mutation and retrieval operations require authentication. Authorization Backend should derive: currentUserId from the authenticated session/token. It should not trust: userId provided by the client. Ownership A user must only be able to: Create → their own saved relationship Read → their own saved products Delete → their own saved relationship Input Validation Validate: Product ID format. Request body. Authentication state. Abuse Protection Potential concerns: Automated save requests. Repeated requests. Excessive wishlist size. Rate limiting should be considered based on existing application infrastructure. Sensitive Data The saved-product relationship itself may not be highly sensitive, but user ownership information should not be exposed across accounts. --- 🔗 PHASE 11 — DEPENDENCY & DATA-FLOW MAPPING 🔄 Save Flow 👤 User ↓ 🖥️ Product UI ↓ 📦 Frontend State ↓ 🌐 POST /saved-products ↓ 🔐 Authentication ↓ ⚙️ Saved Product Service ↓ 🛍️ Product Validation ↓ 💾 Database ↓ 📤 API Response ↓ 🖥️ UI State Update List Flow 👤 User ↓ 🖥️ Saved Products Page ↓ 🌐 GET /saved-products ↓ 🔐 Authentication ↓ ⚙️ Saved Product Service ↓ 💾 Saved Relationship ↓ 🛍️ Product Data ↓ 📤 Response ↓ 🖥️ Product Cards Remove Flow 👤 User ↓ 🖥️ Remove Action ↓ 🌐 DELETE /saved-products/:productId ↓ 🔐 Authentication ↓ 🛡️ Ownership Validation ↓ 💾 Delete Relationship ↓ 📤 Response ↓ 🖥️ UI Update External Dependencies Potential: Existing product service. Existing authentication system. Existing database. Existing API client. No new external service is inherently required. --- 🧪 PHASE 12 — TEST & ACCEPTANCE ARCHITECTURE ✅ Unit Tests Test: Save business logic. Remove business logic. Duplicate-save behavior. Ownership validation. Product validation. API Tests Test: POST save GET saved products DELETE saved product Authorization Tests Verify: Unauthenticated → rejected User A → cannot delete User B's saved product User A → cannot read User B's saved products Database Tests Verify: Duplicate (user, product) → prevented Foreign key integrity → maintained Delete → removes relationship only Component Tests Test: Save button. Saved state. Loading state. Error state. Empty wishlist. E2E Test Login ↓ Open product ↓ Save product ↓ Open saved products ↓ Verify product ↓ Remove product ↓ Verify removal Requirement Traceability Requirement Task Test Acceptance Save product T03 API-01 Product appears saved Remove product T04 API-02 Product removed View saved products T05 E2E-01 Saved product displayed No duplicates T03 DB-01 Only one relationship Ownership T03/T04 SEC-01 Cross-user access rejected Auth required T03-T05 SEC-02 Unauthenticated access rejected --- 🧠 PHASE 13 — IMPLEMENTATION TASK DECOMPOSITION 📋 T01 — Repository Architecture Discovery Objective: Identify actual existing components and conventions. Inspect: Product UI. Product API. Authentication. User model. Database models. Migrations. Tests. Acceptance Criteria: Actual file paths identified. Existing reusable modules identified. No new files proposed unnecessarily. Risk: Medium. --- T02 — Finalize Data Model Objective: Determine whether an existing relationship can support saved products. Output: Confirmed existing model reuse OR Proposed migration. Dependencies: T01. Acceptance Criteria: Duplicate prevention strategy defined. Ownership relationship defined. Migration/rollback strategy documented. Risk: High. --- T03 — Implement Backend Save/Remove Logic Objective: Add saved-product business operations. Dependencies: T01 T02 Acceptance Criteria: Authenticated user can save. Duplicate save is prevented. User can remove their own saved product. Cross-user modification is rejected. Tests: Unit. API. Authorization. --- T04 — Implement Saved Products API Objective: Expose required backend contracts. Dependencies: T03. Acceptance Criteria: Save endpoint works. Remove endpoint works. List endpoint works. Existing API conventions are preserved. --- T05 — Implement Frontend Save Interaction Objective: Add save/remove behavior to existing product UI. Dependencies: T04. Acceptance Criteria: Save control appears in correct existing UI. Loading state works. Saved state updates correctly. Errors are recoverable. --- T06 — Implement Saved Products View Objective: Display user's saved products. Dependencies: T04. Acceptance Criteria: Products load correctly. Empty state exists. Error state exists. Existing product display components are reused where appropriate. --- T07 — Integration & E2E Validation Objective: Validate complete user journey. Dependencies: T03 T04 T05 T06 Acceptance Criteria: Save → View → Remove workflow passes. Existing product workflow remains functional. --- 🔄 PHASE 14 — IMPLEMENTATION ORDER & DEPENDENCY GRAPH 📊 Dependency Graph T01 Repository Discovery │ ▼ T02 Data Model │ ▼ T03 Backend Logic │ ▼ T04 API / \ / \ ▼ ▼ T05 T06 Frontend Saved View \ / \ / ▼ T07 E2E Validation 🔴 Critical Path T01 → T02 → T03 → T04 → T05/T06 → T07 🟢 Parallelizable Work After T04: T05 Frontend Save Interaction + T06 Saved Products View can potentially proceed in parallel. 🔴 Blocking Tasks T01 blocks architectural implementation. T02 blocks database-dependent backend work. T04 blocks frontend API integration. --- 🛠️ PHASE 15 — AI CODING AGENT EXECUTION BLUEPRINT 🤖 Step 1 — Inspect Repository 🔍 Context The repository structure is incomplete. Objective Discover actual architecture before modifying files. Inspect Authentication Product components Product APIs Database models Migration system API conventions Testing conventions Stop Condition If an existing saved-product implementation is discovered, stop and reassess instead of creating duplicate functionality. --- Step 2 — Confirm Data Architecture 🗄️ Objective Determine whether the current database can represent: User → Product saved relationships. Constraints Do not duplicate product records. Follow existing migration conventions. Preserve existing data. Verification Confirm: Unique user/product relationship Foreign-key strategy Index strategy Rollback --- Step 3 — Implement Backend Logic ⚙️ Objective Implement save/remove/list behavior using existing backend architecture. Constraints Reuse authentication. Keep business logic outside controllers where existing architecture supports services. Enforce ownership server-side. Verification Run backend unit and API tests. Checkpoint Do not proceed if authorization tests fail. --- Step 4 — Implement API Contract 🔌 Objective Expose the finalized saved-product operations. Verification Confirm: Authentication Validation Responses Errors Duplicate handling --- Step 5 — Implement Frontend 🖥️ Objective Integrate saved-product behavior into existing product UI. Constraints Reuse existing product components. Preserve existing UI conventions. Do not duplicate API state unnecessarily. Verification Test: Save Remove Loading Error Empty state --- Step 6 — End-to-End Validation 🧪 Objective Verify the complete feature. Test Login → Save product → Open saved products → Verify product → Remove → Verify removal Stop Conditions Stop and investigate if: Cross-user access succeeds. Duplicate records are created. Existing product functionality breaks. API contract differs from frontend expectations. Database migration cannot safely roll back. --- ⚠️ PHASE 16 — FINAL FEATURE-TO-CODE IMPLEMENTATION REPORT 🏆 1️⃣ Feature Summary Build a user-specific saved-products capability that allows authenticated users to save, view, and remove products without duplicating product data. --- 2️⃣ Requirements Breakdown 📋 Functional Save product. Remove product. View saved products. Display saved state. Handle loading/errors/empty states. Security Authentication required. Backend ownership enforcement. Duplicate prevention. Input validation. Compatibility Existing product functionality remains unchanged. Existing authentication should be reused. --- 3️⃣ User Journey 👤 Product ↓ Save ↓ Backend authentication ↓ Validate product ↓ Persist relationship ↓ Saved state ↓ Saved Products ↓ Remove ↓ Relationship deleted --- 4️⃣ Architecture Impact 🏗️ Layer Impact Frontend MODIFY/CREATE Backend CREATE/MODIFY API CREATE Database PROPOSED CHANGE Authentication REUSE Authorization ADD/ENFORCE External services None inherently required Observability Potential addition Infrastructure No inherent change --- 5️⃣ File Change Map 📁 Exact paths remain unresolved because repository evidence is incomplete. Action File Responsibility Change MODIFY Existing product component Product UI Add save state CREATE/MODIFY Existing frontend feature location Saved products Add saved-products view CREATE/MODIFY Existing backend auth/feature location Business logic Save/remove/list CREATE/MODIFY Existing API route location API Saved-product endpoints CREATE/MODIFY Existing migration location Database Relationship CREATE/MODIFY Existing test locations Validation Full test coverage --- 6️⃣ Component & Module Plan 🧩 ProductCard ↓ SaveProductAction ↓ Saved Product API ↓ Saved Product Service ↓ Database Saved products: SavedProductsPage ↓ Saved Products API ↓ Product Data ↓ Existing ProductCard --- 7️⃣ API Contract Plan 🔌 Proposed POST /api/saved-products DELETE /api/saved-products/:productId GET /api/saved-products All require authentication. Exact route naming must follow repository conventions after T01. --- 8️⃣ Database Change Plan 💾 Potential new relationship: saved_products with: user_id product_id created_at and duplicate protection: UNIQUE(user_id, product_id) This remains a proposed model until the existing schema is inspected. --- 9️⃣ Security & Authorization Plan 🔐 Authentication ↓ Current User ↓ Backend Authorization ↓ User-Owned Saved Products Frontend checks are insufficient by themselves. --- 🔟 Data & Control Flow 🔄 User ↓ React UI ↓ API Client ↓ Authenticated API ↓ Saved Product Service ↓ Product Validation ↓ Database ↓ API Response ↓ React State ↓ UI --- 1️⃣1️⃣ Task Breakdown 🧠 T01 → Repository discovery T02 → Data model T03 → Backend logic T04 → API T05 → Product UI T06 → Saved-products UI T07 → E2E/regression validation --- 1️⃣2️⃣ Dependency Graph 🔗 T01 ↓ T02 ↓ T03 ↓ T04 ↙ ↘ T05 T06 ↘ ↙ T07 --- 1️⃣3️⃣ Testing Plan 🧪 Unit Save logic. Remove logic. Duplicate prevention. Ownership. API Save. Remove. List. Authentication. Database Uniqueness. Foreign keys. Relationship deletion. Frontend Saved state. Loading. Errors. Empty state. E2E Login → Save → View → Remove Regression Existing: Login Product listing Product details Search must continue working. --- 1️⃣4️⃣ AI Coding Agent Execution Plan 🤖 1. Inspect repository. 2. Identify existing authentication and product architecture. 3. Identify existing database models and migration conventions. 4. Confirm whether saved-product functionality already exists. 5. Finalize data model. 6. Implement backend business logic. 7. Add API contract. 8. Add backend tests. 9. Integrate frontend save/remove behavior. 10. Build saved-products view. 11. Add component tests. 12. Run integration tests. 13. Run E2E tests. 14. Run regression suite. 15. Review authorization and database constraints. 16. Produce final implementation summary. --- 1️⃣5️⃣ Risk & Unknowns Register ⚠️ Risk / Unknown Impact Resolution Exact database schema unknown High Inspect repository Existing product API unknown High Inspect backend Auth mechanism details unknown High Inspect auth implementation Frontend state management unknown Medium Inspect existing components Migration framework unknown High Inspect repository Email/external service None expected No new service required Wishlist UI location unknown Medium Follow existing navigation conventions Product deletion behavior unknown Medium Inspect product lifecycle Key Assumption The feature is being added to an existing application that already has users and products. --- ✅ 1️⃣6️⃣ DEFINITION OF DONE Requirements [ ] Users can save products. [ ] Users can remove products. [ ] Users can view saved products. [ ] Duplicate saves are prevented. Frontend [ ] Save control implemented. [ ] Saved state implemented. [ ] Loading state implemented. [ ] Error state implemented. [ ] Empty state implemented. [ ] Accessibility verified. Backend [ ] APIs implemented. [ ] Business logic separated appropriately. [ ] Input validation implemented. [ ] Authentication enforced. [ ] Ownership enforced. Database [ ] Relationship implemented if required. [ ] Uniqueness enforced. [ ] Foreign keys verified. [ ] Indexes evaluated. [ ] Migration tested. [ ] Rollback tested. Testing [ ] Unit tests. [ ] API tests. [ ] Database tests. [ ] Authorization tests. [ ] Component tests. [ ] E2E test. [ ] Regression tests. Observability [ ] Relevant failures logged. [ ] Sensitive data excluded from logs. [ ] Production errors are observable. Documentation [ ] API behavior documented according to repository conventions. [ ] New architectural decisions documented if necessary. Final Acceptance Requirement ↓ Architecture ↓ Actual Repository File ↓ Component/API/Data Change ↓ Implementation Task ↓ Test ↓ Acceptance Criterion Result: The feature is complete only when the full Save → View → Remove workflow works for the correct authenticated user, unauthorized access is rejected, duplicates cannot be created, existing product functionality remains intact, and the relevant automated tests pass.