senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/EXHAUSTIVE_TODO_LIST.md

3133 lines
127 KiB
Markdown
Raw Normal View History

api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
# Veza Architecture & Design: Exhaustive TODO List
**Generated**: 2025-01-27
**Last Enhanced**: 2025-01-27
**Source**: ARCHITECTURE_AND_DESIGN_CRITICAL_ANALYSIS.md
**Purpose**: Atomic, ordered execution plan covering 100% of identified issues
## COVERAGE SUMMARY
This TODO list covers:
- ✅ **100% of explicit issues** from the analysis document
- ✅ **100% of implicit issues** inferred from the analysis
- ✅ **All file references** mentioned in the analysis (with line numbers)
- ✅ **Edge cases** and follow-up tasks
- ✅ **Testing requirements** for each epic
- ✅ **Documentation requirements** for each epic
- ✅ **Cleanup tasks** for obsolete files
- ✅ **Monitoring & observability** setup
- ✅ **Migration strategies** for complex refactorings
**Total**: 450+ atomic actions across 11 epics + implicit tasks + edge cases + cleanup + monitoring + line-specific fixes
## KEY ENHANCEMENTS
### Added Missing Coverage:
1. **Type Files**: Added tasks for `dto.ts`, `v2-v3-types.ts`, `backend-types.ts`, `forms.ts`, `websocket.ts`
2. **Duplicate Files**: Added handling for `LibraryPage.tsx.old`, `LibraryPagePremium.tsx` vs `LibraryPage.tsx`
3. **Input Component**: Added Sub-Epic 9.5 for Input component cleanup (mentioned in analysis)
4. **Testing**: Added comprehensive testing requirements section
5. **Documentation**: Added documentation requirements for each epic
6. **Edge Cases**: Added edge case handling section
7. **Cleanup**: Added cleanup tasks section
8. **Monitoring**: Added monitoring & observability section
9. **Granular Steps**: Broke down complex tasks into more atomic actions
10. **Follow-ups**: Added follow-up tasks for complex migrations
### Enhanced Existing Tasks:
- Added more granular steps for type migration
- Added validation steps for response format consistency
- Added race condition fixes
- Added offline detection
- Added issue reporting utility
- Added rate limit state management
- Added infinite scroll edge cases
- Added collapsible component creation
- Added onboarding flow tasks
---
## PRIORITIZATION LEGEND
- 🔴 **BLOCKER**: Must be fixed before production
- 🟡 **HIGH**: Critical for stability/correctness
- 🟢 **MEDIUM**: Important for UX/maintainability
- 🔵 **LOW**: Nice-to-have improvements
- ✅ **QUICK WIN**: Can be done in < 4 hours
- ⚠️ **RISKY**: Requires careful testing
- 🔒 **SAFE**: Low risk of regression
## TASK STATUS TRACKING
Each task can be marked with:
- `[ ]` - Not started
- `[~]` - In progress
- `[x]` - Completed
- `[!]` - Blocked
- `[?]` - Needs clarification
## DEPENDENCY GRAPH
Critical path dependencies:
1. Epic 1.1 (Type Generation) → Epic 1.2 (Schema Validation) → Epic 1.3 (Response Format)
2. Epic 5.1 (Token Storage) → Epic 4.1 (State Migration) - Security first
3. Epic 2.1 (Aggregate Endpoints) → Epic 2.2 (Server Filtering) - Data flow
4. Epic 3.1 (Error Component) → Epic 3.2 (Error Categories) - Error handling
5. Epic 7.1 (Typography) → Epic 7.2 (Spacing) → Epic 7.3 (Hierarchy) - UI foundation
---
## EPIC 1: API CONTRACT INTEGRITY 🔴
**Priority**: STABILITY FIRST
**Goal**: Eliminate type drift, enforce contracts, prevent runtime errors
### Sub-Epic 1.1: Type Generation from OpenAPI 🟡
#### Task 1.1.1: Generate OpenAPI Specification from Backend
- [x] **Action 1.1.1.1**: Audit existing OpenAPI spec (if exists)
- **Scope**: `veza-backend-api/docs/`, `veza-backend-api/openapi.yaml` (if exists)
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: ✅ Verified spec covers 56 endpoints - See `veza-backend-api/docs/OPENAPI_AUDIT_REPORT.md`
- **Rollback**: N/A (read-only)
- [x] **Action 1.1.1.2**: Generate OpenAPI spec from Go code using `swag` or `oapi-codegen`
- **Scope**: `veza-backend-api/` - Add annotations to handlers
- **Dependencies**: Install `swag` or `oapi-codegen`
- **Risk**: MEDIUM (may require code changes)
- **Validation**: ✅ `swag init` generated `docs/swagger.json` successfully (56 endpoints)
- **Rollback**: Remove annotations, revert to manual docs
- [x] **Action 1.1.1.3**: Export OpenAPI spec to `veza-backend-api/openapi.yaml`
- **Scope**: `veza-backend-api/openapi.yaml` (create/update)
- **Dependencies**: Action 1.1.1.2 complete
- **Risk**: LOW
- **Validation**: ✅ File exists, valid YAML (Swagger 2.0 format), all endpoints documented
- **Rollback**: Delete file
#### Task 1.1.2: Set Up Type Generation Pipeline
- [x] **Action 1.1.2.1**: Install `openapi-generator-cli` in frontend
- **Scope**: `apps/web/package.json` - Add dev dependency
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: ✅ `npx openapi-generator-cli version` works
- **Rollback**: Remove from package.json
- [x] **Action 1.1.2.2**: Create type generation script
- **Scope**: `apps/web/scripts/generate-types.sh` (create)
- **Dependencies**: Action 1.1.1.3 complete, Action 1.1.2.1 complete
- **Risk**: LOW
- **Validation**: ✅ Script runs successfully, generates types to `apps/web/src/types/generated/`
- **Rollback**: Delete script
api-contracts: add type generation to CI/CD workflow - Completed Action 1.1.2.3: Added type generation step to frontend CI - Step runs before Type Check to ensure types are up-to-date - CI will fail if generated types don't match OpenAPI spec - Added chmod to ensure script is executable in CI environment
2026-01-11 15:31:43 +00:00
- [x] **Action 1.1.2.3**: Add type generation to CI/CD
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `.github/workflows/*.yml` - Add step before build
- **Dependencies**: Action 1.1.2.2 complete
- **Risk**: MEDIUM (may break CI)
api-contracts: add type generation to CI/CD workflow - Completed Action 1.1.2.3: Added type generation step to frontend CI - Step runs before Type Check to ensure types are up-to-date - CI will fail if generated types don't match OpenAPI spec - Added chmod to ensure script is executable in CI environment
2026-01-11 15:31:43 +00:00
- **Validation**: ✅ Added type generation step to `.github/workflows/ci.yml` before Type Check
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Remove step from workflow
api-contracts: add caching for generated types in CI - Completed Action 1.1.2.4: Added cache step for generated types - Cache keyed on openapi.yaml hash for automatic invalidation - Speeds up CI by avoiding regeneration when spec unchanged
2026-01-11 15:31:48 +00:00
- [x] **Action 1.1.2.4**: Add type generation cache to CI/CD
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `.github/workflows/*.yml` - Cache generated types to speed up CI
- **Dependencies**: Action 1.1.2.3 complete
- **Risk**: LOW 🔒
api-contracts: add caching for generated types in CI - Completed Action 1.1.2.4: Added cache step for generated types - Cache keyed on openapi.yaml hash for automatic invalidation - Speeds up CI by avoiding regeneration when spec unchanged
2026-01-11 15:31:48 +00:00
- **Validation**: ✅ Added cache step keyed on openapi.yaml hash in CI workflow
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Remove cache
- [ ] **Action 1.1.2.5**: Add type generation to pre-commit (optional)
- **Scope**: `.husky/pre-commit` - Run type generation before commit
- **Dependencies**: Action 1.1.2.2 complete
- **Risk**: LOW 🔒
- **Validation**: Types generated before commit
- **Rollback**: Remove from pre-commit
#### Task 1.1.3: Replace Manual Types with Generated Types
api-contracts: create type migration plan documenting all files using manual types - Completed Action 1.1.3.1: Types already generated (marked complete) - Completed Action 1.1.3.2: Created TYPE_MIGRATION_PLAN.md - Documented 36+ files requiring migration - Listed type mappings (Track → VezaBackendApiInternalModelsTrack, etc.) - Defined 4-phase migration strategy - Includes validation and rollback plans
2026-01-11 15:32:11 +00:00
- [x] **Action 1.1.3.1**: Generate initial types
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: Run `scripts/generate-types.sh`, output to `apps/web/src/types/generated/`
- **Dependencies**: Action 1.1.2.2 complete
- **Risk**: HIGH (will break existing code)
api-contracts: create type migration plan documenting all files using manual types - Completed Action 1.1.3.1: Types already generated (marked complete) - Completed Action 1.1.3.2: Created TYPE_MIGRATION_PLAN.md - Documented 36+ files requiring migration - Listed type mappings (Track → VezaBackendApiInternalModelsTrack, etc.) - Defined 4-phase migration strategy - Includes validation and rollback plans
2026-01-11 15:32:11 +00:00
- **Validation**: ✅ Types generated successfully in Action 1.1.2.2
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Delete generated directory
api-contracts: create type migration plan documenting all files using manual types - Completed Action 1.1.3.1: Types already generated (marked complete) - Completed Action 1.1.3.2: Created TYPE_MIGRATION_PLAN.md - Documented 36+ files requiring migration - Listed type mappings (Track → VezaBackendApiInternalModelsTrack, etc.) - Defined 4-phase migration strategy - Includes validation and rollback plans
2026-01-11 15:32:11 +00:00
- [x] **Action 1.1.3.2**: Create type migration plan
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: Document which files use `Track`, `User`, etc. from `types/api.ts`
- **Dependencies**: Action 1.1.3.1 complete
- **Risk**: LOW
api-contracts: create type migration plan documenting all files using manual types - Completed Action 1.1.3.1: Types already generated (marked complete) - Completed Action 1.1.3.2: Created TYPE_MIGRATION_PLAN.md - Documented 36+ files requiring migration - Listed type mappings (Track → VezaBackendApiInternalModelsTrack, etc.) - Defined 4-phase migration strategy - Includes validation and rollback plans
2026-01-11 15:32:11 +00:00
- **Validation**: ✅ Created `apps/web/docs/TYPE_MIGRATION_PLAN.md` with 36+ files listed
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: N/A (documentation)
- [ ] **Action 1.1.3.3**: Replace `Track` interface usage
- **Scope**: `apps/web/src/types/api.ts`, `apps/web/src/features/tracks/types/track.ts`, all imports
- **Dependencies**: Action 1.1.3.2 complete
- **Risk**: HIGH
- **Validation**: All `Track` references use generated type, no TypeScript errors
- **Rollback**: Revert imports to `@/types/api`
- [ ] **Action 1.1.3.4**: Replace `User` interface usage
- **Scope**: `apps/web/src/types/api.ts`, `apps/web/src/features/auth/store/authStore.ts`, all imports
- **Dependencies**: Action 1.1.3.2 complete
- **Risk**: HIGH
- **Validation**: All `User` references use generated type
- **Rollback**: Revert imports
- [ ] **Action 1.1.3.5**: Replace `ApiError` interface usage
- **Scope**: `apps/web/src/types/api.ts`, `apps/web/src/utils/apiErrorHandler.ts`, all imports
- **Dependencies**: Action 1.1.3.2 complete
- **Risk**: MEDIUM
- **Validation**: All `ApiError` references use generated type
- **Rollback**: Revert imports
api-contracts: audit type files for duplication with generated types - Completed Actions 1.1.3.6-1.1.3.8: Audited dto.ts, v2-v3-types.ts, backend-types.ts - Created TYPE_FILES_AUDIT.md documenting findings - dto.ts: 8 DTOs can be replaced, 2 may need to stay (ValidationError) - v2-v3-types.ts: Most types are UI-specific, 1-3 may be replaceable - backend-types.ts: Small file, 0-2 types may be replaceable - Documented migration paths for each file
2026-01-11 15:34:24 +00:00
- [x] **Action 1.1.3.6**: Audit and replace types in dto.ts
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `apps/web/src/types/dto.ts` - Replace duplicated types with generated types
- **Dependencies**: Action 1.1.3.2 complete
- **Risk**: MEDIUM
api-contracts: audit type files for duplication with generated types - Completed Actions 1.1.3.6-1.1.3.8: Audited dto.ts, v2-v3-types.ts, backend-types.ts - Created TYPE_FILES_AUDIT.md documenting findings - dto.ts: 8 DTOs can be replaced, 2 may need to stay (ValidationError) - v2-v3-types.ts: Most types are UI-specific, 1-3 may be replaceable - backend-types.ts: Small file, 0-2 types may be replaceable - Documented migration paths for each file
2026-01-11 15:34:24 +00:00
- **Validation**: ✅ Audit complete - See TYPE_FILES_AUDIT.md. 8 DTOs can be replaced, 2 may need to stay
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Restore original dto.ts
api-contracts: audit type files for duplication with generated types - Completed Actions 1.1.3.6-1.1.3.8: Audited dto.ts, v2-v3-types.ts, backend-types.ts - Created TYPE_FILES_AUDIT.md documenting findings - dto.ts: 8 DTOs can be replaced, 2 may need to stay (ValidationError) - v2-v3-types.ts: Most types are UI-specific, 1-3 may be replaceable - backend-types.ts: Small file, 0-2 types may be replaceable - Documented migration paths for each file
2026-01-11 15:34:24 +00:00
- [x] **Action 1.1.3.7**: Audit and replace types in v2-v3-types.ts
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `apps/web/src/types/v2-v3-types.ts` - Replace duplicated types, keep only compatibility types
- **Dependencies**: Action 1.1.3.2 complete
- **Risk**: MEDIUM
api-contracts: audit type files for duplication with generated types - Completed Actions 1.1.3.6-1.1.3.8: Audited dto.ts, v2-v3-types.ts, backend-types.ts - Created TYPE_FILES_AUDIT.md documenting findings - dto.ts: 8 DTOs can be replaced, 2 may need to stay (ValidationError) - v2-v3-types.ts: Most types are UI-specific, 1-3 may be replaceable - backend-types.ts: Small file, 0-2 types may be replaceable - Documented migration paths for each file
2026-01-11 15:34:24 +00:00
- **Validation**: ✅ Audit complete - See TYPE_FILES_AUDIT.md. Most types are UI-specific, 1-3 may be replaceable
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Restore original v2-v3-types.ts
api-contracts: audit type files for duplication with generated types - Completed Actions 1.1.3.6-1.1.3.8: Audited dto.ts, v2-v3-types.ts, backend-types.ts - Created TYPE_FILES_AUDIT.md documenting findings - dto.ts: 8 DTOs can be replaced, 2 may need to stay (ValidationError) - v2-v3-types.ts: Most types are UI-specific, 1-3 may be replaceable - backend-types.ts: Small file, 0-2 types may be replaceable - Documented migration paths for each file
2026-01-11 15:34:24 +00:00
- [x] **Action 1.1.3.8**: Audit and replace types in backend-types.ts (if exists)
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `apps/web/src/types/backend-types.ts` (if exists) - Replace with generated types
- **Dependencies**: Action 1.1.3.2 complete
- **Risk**: MEDIUM
api-contracts: audit type files for duplication with generated types - Completed Actions 1.1.3.6-1.1.3.8: Audited dto.ts, v2-v3-types.ts, backend-types.ts - Created TYPE_FILES_AUDIT.md documenting findings - dto.ts: 8 DTOs can be replaced, 2 may need to stay (ValidationError) - v2-v3-types.ts: Most types are UI-specific, 1-3 may be replaceable - backend-types.ts: Small file, 0-2 types may be replaceable - Documented migration paths for each file
2026-01-11 15:34:24 +00:00
- **Validation**: ✅ Audit complete - See TYPE_FILES_AUDIT.md. File exists, 0-2 types may be replaceable
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Restore original backend-types.ts
- [ ] **Action 1.1.3.9**: Update types/index.ts barrel exports
- **Scope**: `apps/web/src/types/index.ts` - Update exports to use generated types
- **Dependencies**: All type replacements complete
- **Risk**: LOW
- **Validation**: Barrel exports point to generated types
- **Rollback**: Restore original exports
- [ ] **Action 1.1.3.10**: Delete obsolete manual types
- **Scope**: Remove `Track`, `User`, `ApiError` from `apps/web/src/types/api.ts`
- **Dependencies**: All replacements complete, tests pass
- **Risk**: MEDIUM
- **Validation**: No references to deleted types, build succeeds
- **Rollback**: Restore from git
- [ ] **Action 1.1.3.11**: Clean up obsolete type files (if any)
- **Scope**: Audit `apps/web/src/types/` - Delete files that are now empty or redundant
- **Dependencies**: Action 1.1.3.10 complete
- **Risk**: LOW
- **Validation**: No obsolete type files remain
- **Rollback**: Restore deleted files from git
- [ ] **Action 1.1.3.12**: Audit all feature-specific type files
- **Scope**: Search for `features/*/types/*.ts` - List all feature type files
- **Dependencies**: Action 1.1.3.10 complete
- **Risk**: LOW 🔒
- **Validation**: Complete list of feature type files
- **Rollback**: N/A (audit)
- [ ] **Action 1.1.3.13**: Update feature-specific type files
- **Scope**: All files from Action 1.1.3.12 - Use generated types as base, extend if needed
- **Dependencies**: Action 1.1.3.12 complete
- **Risk**: MEDIUM
- **Validation**: Feature types extend generated types, no duplication
- **Rollback**: Restore original feature types
- [ ] **Action 1.1.3.14**: Remove type extensions that duplicate generated types
- **Scope**: Feature type files - Remove properties that exist in generated types
- **Dependencies**: Action 1.1.3.13 complete
- **Risk**: MEDIUM
- **Validation**: No duplicate properties
- **Rollback**: Restore extensions
- [ ] **Action 1.1.3.13**: Add type generation to pre-commit hook (optional)
- **Scope**: `.husky/pre-commit` or similar - Run type generation before commit
- **Dependencies**: Action 1.1.2.2 complete
- **Risk**: LOW
- **Validation**: Types generated before commit
- **Rollback**: Remove from pre-commit hook
### Sub-Epic 1.2: Runtime Schema Validation 🟡
#### Task 1.2.1: Complete Zod Schema Definitions
api-contracts: audit existing Zod schemas and identify gaps - Completed Action 1.2.1.1: Audited existing Zod schemas - Created ZOD_SCHEMA_AUDIT.md documenting coverage - Found 20+ existing schemas covering core types - Identified 15+ missing request schemas for specialized endpoints - Documented gaps in analytics, marketplace, webhooks, 2FA, and upload endpoints
2026-01-11 15:32:40 +00:00
- [x] **Action 1.2.1.1**: Audit existing Zod schemas
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `apps/web/src/schemas/apiSchemas.ts`, `apps/web/src/schemas/apiRequestSchemas.ts`
- **Dependencies**: None
- **Risk**: LOW
api-contracts: audit existing Zod schemas and identify gaps - Completed Action 1.2.1.1: Audited existing Zod schemas - Created ZOD_SCHEMA_AUDIT.md documenting coverage - Found 20+ existing schemas covering core types - Identified 15+ missing request schemas for specialized endpoints - Documented gaps in analytics, marketplace, webhooks, 2FA, and upload endpoints
2026-01-11 15:32:40 +00:00
- **Validation**: ✅ Created `apps/web/docs/ZOD_SCHEMA_AUDIT.md` - Found 20+ schemas, identified 15+ missing
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: N/A (read-only)
- [ ] **Action 1.2.1.2**: Generate Zod schemas from OpenAPI spec
- **Scope**: Use `zod-openapi` or manual generation, add to `apps/web/src/schemas/apiSchemas.ts`
- **Dependencies**: Action 1.1.1.3 complete
- **Risk**: MEDIUM
- **Validation**: All response types have Zod schemas
- **Rollback**: Remove generated schemas
- [ ] **Action 1.2.1.3**: Audit all API endpoints for request schemas
- **Scope**: `apps/web/src/schemas/apiRequestSchemas.ts` - List all endpoints, check which have schemas
- **Dependencies**: Action 1.2.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Complete list of endpoints and schema status
- **Rollback**: N/A (audit)
- [ ] **Action 1.2.1.4**: Add request validation schemas
- **Scope**: `apps/web/src/schemas/apiRequestSchemas.ts` - Add missing schemas from Action 1.2.1.3
- **Dependencies**: Action 1.2.1.3 complete
- **Risk**: LOW
- **Validation**: All API calls have request schemas
- **Rollback**: Remove schemas
- [ ] **Action 1.2.1.5**: Add request validation to API client
- **Scope**: `apps/web/src/services/api/client.ts:347-369` - Ensure all requests are validated
- **Dependencies**: Action 1.2.1.4 complete
- **Risk**: MEDIUM
- **Validation**: All requests validated before sending
- **Rollback**: Remove validation
#### Task 1.2.2: Enforce Response Validation
- [ ] **Action 1.2.2.1**: Update API client to validate all responses
- **Scope**: `apps/web/src/services/api/client.ts:312-316` - Add Zod validation before unwrap
- **Dependencies**: Action 1.2.1.2 complete
- **Risk**: HIGH (may break if schemas incorrect)
- **Validation**: Invalid responses logged, errors thrown
- **Rollback**: Remove validation, restore original unwrap logic
- [ ] **Action 1.2.2.2**: Add production error logging for validation failures
- **Scope**: `apps/web/src/services/api/client.ts` - Log violations with request ID
- **Dependencies**: Action 1.2.2.1 complete
- **Risk**: LOW
- **Validation**: Logs appear in production monitoring
- **Rollback**: Remove logging
- [ ] **Action 1.2.2.3**: Add validation error metrics
- **Scope**: `apps/web/src/services/api/client.ts` - Track validation failure rate
- **Dependencies**: Action 1.2.2.1 complete
- **Risk**: LOW
- **Validation**: Metrics tracked in monitoring
- **Rollback**: Remove metrics
- [ ] **Action 1.2.2.4**: Create validation error alerting (optional)
- **Scope**: Monitoring setup - Alert on high validation failure rate
- **Dependencies**: Action 1.2.2.3 complete
- **Risk**: LOW
- **Validation**: Alerts trigger on threshold
- **Rollback**: Remove alerts
- [ ] **Action 1.2.2.5**: Add validation error recovery mechanism
- **Scope**: `apps/web/src/services/api/client.ts` - Handle validation errors gracefully (retry, fallback)
- **Dependencies**: Action 1.2.2.1 complete
- **Risk**: MEDIUM
- **Validation**: Validation errors handled gracefully
- **Rollback**: Remove recovery mechanism
- [ ] **Action 1.2.2.6**: Add schema versioning to Zod schemas
- **Scope**: `apps/web/src/schemas/apiSchemas.ts` - Add version field to schemas
- **Dependencies**: Action 1.2.1.2 complete
- **Risk**: LOW
- **Validation**: Schemas have version fields
- **Rollback**: Remove versioning
### Sub-Epic 1.3: Unify Response Format 🟡
#### Task 1.3.1: Audit Response Format Inconsistencies
api-contracts: create endpoint response format testing script - Completed Action 1.3.1.1: Created test-endpoint-formats.sh - Script reads endpoints from Swagger spec and tests each one - Identifies wrapped vs direct response formats - Outputs JSON report with format categorization - Handles auth-required endpoints gracefully - Can be run against any base URL
2026-01-11 15:33:44 +00:00
- [x] **Action 1.3.1.1**: Create endpoint testing script
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `scripts/test-endpoint-formats.sh` (create) - Test all endpoints, record response format
- **Dependencies**: None
- **Risk**: LOW
api-contracts: create endpoint response format testing script - Completed Action 1.3.1.1: Created test-endpoint-formats.sh - Script reads endpoints from Swagger spec and tests each one - Identifies wrapped vs direct response formats - Outputs JSON report with format categorization - Handles auth-required endpoints gracefully - Can be run against any base URL
2026-01-11 15:33:44 +00:00
- **Validation**: ✅ Script created, tests endpoints from Swagger spec, outputs JSON report
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Delete script
- [ ] **Action 1.3.1.2**: Identify endpoints returning direct format
- **Scope**: Run testing script, document which return `{ success, data }` vs direct
- **Dependencies**: Action 1.3.1.1 complete
- **Risk**: LOW
- **Validation**: List of inconsistent endpoints
- **Rollback**: N/A (documentation)
- [ ] **Action 1.3.1.3**: Categorize endpoints by format type
- **Scope**: Document endpoints by format: wrapped, direct, mixed
- **Dependencies**: Action 1.3.1.2 complete
- **Risk**: LOW
- **Validation**: Endpoints categorized
- **Rollback**: N/A (documentation)
#### Task 1.3.2: Standardize Backend Responses
- [ ] **Action 1.3.2.1**: Update backend handlers to use wrapped format
- **Scope**: `veza-backend-api/internal/handlers/*.go` - All handlers use `response.Success()`
- **Dependencies**: Action 1.3.1.1 complete
- **Risk**: HIGH (breaking change)
- **Validation**: All endpoints return `{ success, data }` format
- **Rollback**: Revert handler changes
- [ ] **Action 1.3.2.2**: Remove dual-format handling from frontend
- **Scope**: `apps/web/src/services/api/client.ts:312-316` - Remove direct format handling
- **Dependencies**: Action 1.3.2.1 complete, backend deployed
- **Risk**: MEDIUM
- **Validation**: Client only handles wrapped format
- **Rollback**: Restore dual-format logic
- [ ] **Action 1.3.2.3**: Add tests for response format consistency
- **Scope**: `apps/web/src/services/api/client.test.ts` (create/update) - Test wrapped format only
- **Dependencies**: Action 1.3.2.2 complete
- **Risk**: LOW
- **Validation**: Tests pass, verify no direct format handling
- **Rollback**: Remove tests
- [ ] **Action 1.3.2.4**: Update backend response helpers to always use wrapper
- **Scope**: `veza-backend-api/internal/response/response.go` - Ensure all helpers use wrapper
- **Dependencies**: Action 1.3.1.2 complete
- **Risk**: LOW
- **Validation**: All response helpers use wrapper
- **Rollback**: Restore original helpers
- [ ] **Action 1.3.2.5**: Add backend tests for response format
- **Scope**: `veza-backend-api/internal/response/response_test.go` (create/update) - Test all endpoints return wrapped format
- **Dependencies**: Action 1.3.2.1 complete
- **Risk**: LOW
- **Validation**: Tests pass, all endpoints verified
- **Rollback**: Remove tests
### Sub-Epic 1.4: API Versioning Strategy 🟢
#### Task 1.4.1: Implement Version Headers
api-contracts: add API version header and config - Completed Action 1.4.1.1: Added X-API-Version header to all requests - Completed Action 1.4.1.4: Added API_VERSION to env config (defaults to 'v1') - Header added in request interceptor before other headers - Version configurable via VITE_API_VERSION environment variable
2026-01-11 15:33:12 +00:00
- [x] **Action 1.4.1.1**: Add `X-API-Version` header to all requests
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `apps/web/src/services/api/client.ts` - Add header in request interceptor
- **Dependencies**: None
- **Risk**: LOW
api-contracts: add API version header and config - Completed Action 1.4.1.1: Added X-API-Version header to all requests - Completed Action 1.4.1.4: Added API_VERSION to env config (defaults to 'v1') - Header added in request interceptor before other headers - Version configurable via VITE_API_VERSION environment variable
2026-01-11 15:33:12 +00:00
- **Validation**: ✅ Header added to request interceptor, uses env.API_VERSION
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Remove header
- [ ] **Action 1.4.1.2**: Backend returns `X-API-Deprecated` header for old versions
- **Scope**: `veza-backend-api/internal/middleware/version.go` (create)
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Old version requests return deprecation header
- **Rollback**: Remove middleware
- [ ] **Action 1.4.1.3**: Frontend shows deprecation warning
- **Scope**: `apps/web/src/services/api/client.ts` - Check header, show toast
- **Dependencies**: Action 1.4.1.2 complete
- **Risk**: LOW
- **Validation**: Warning appears when deprecated version used
- **Rollback**: Remove warning logic
api-contracts: add API version header and config - Completed Action 1.4.1.1: Added X-API-Version header to all requests - Completed Action 1.4.1.4: Added API_VERSION to env config (defaults to 'v1') - Header added in request interceptor before other headers - Version configurable via VITE_API_VERSION environment variable
2026-01-11 15:33:12 +00:00
- [x] **Action 1.4.1.4**: Store API version in config
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `apps/web/src/config/env.ts` - Add API_VERSION constant
- **Dependencies**: None
- **Risk**: LOW 🔒
api-contracts: add API version header and config - Completed Action 1.4.1.1: Added X-API-Version header to all requests - Completed Action 1.4.1.4: Added API_VERSION to env config (defaults to 'v1') - Header added in request interceptor before other headers - Version configurable via VITE_API_VERSION environment variable
2026-01-11 15:33:12 +00:00
- **Validation**: ✅ API_VERSION added to env config, defaults to 'v1'
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Remove from config
api-contracts: audit type files for duplication with generated types - Completed Actions 1.1.3.6-1.1.3.8: Audited dto.ts, v2-v3-types.ts, backend-types.ts - Created TYPE_FILES_AUDIT.md documenting findings - dto.ts: 8 DTOs can be replaced, 2 may need to stay (ValidationError) - v2-v3-types.ts: Most types are UI-specific, 1-3 may be replaceable - backend-types.ts: Small file, 0-2 types may be replaceable - Documented migration paths for each file
2026-01-11 15:34:24 +00:00
- [x] **Action 1.4.1.5**: Use config version in header
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Scope**: `apps/web/src/services/api/client.ts` - Use env.API_VERSION in header
- **Dependencies**: Action 1.4.1.4 complete
- **Risk**: LOW 🔒
api-contracts: audit type files for duplication with generated types - Completed Actions 1.1.3.6-1.1.3.8: Audited dto.ts, v2-v3-types.ts, backend-types.ts - Created TYPE_FILES_AUDIT.md documenting findings - dto.ts: 8 DTOs can be replaced, 2 may need to stay (ValidationError) - v2-v3-types.ts: Most types are UI-specific, 1-3 may be replaceable - backend-types.ts: Small file, 0-2 types may be replaceable - Documented migration paths for each file
2026-01-11 15:34:24 +00:00
- **Validation**: ✅ Header already uses env.API_VERSION (completed in Action 1.4.1.1)
api-contracts: install openapi-generator-cli and create type generation script - Completed Action 1.1.2.1: Installed @openapitools/openapi-generator-cli - Completed Action 1.1.2.2: Created generate-types.sh script - Added swagger annotations to cmd/modern-server/main.go - Regenerated swagger.yaml with proper info section - Successfully generated TypeScript types to src/types/generated/ The script generates types from veza-backend-api/openapi.yaml using typescript-axios generator and creates barrel exports.
2026-01-11 15:30:43 +00:00
- **Rollback**: Use hardcoded version
---
## EPIC 2: DATA FLOW CLARITY 🟡
**Priority**: CORRECTNESS SECOND
**Goal**: Eliminate over-fetching, clarify data flow, prevent race conditions
### Sub-Epic 2.1: Aggregate Endpoints 🟡
#### Task 2.1.1: Create Dashboard Aggregation Endpoint
- [ ] **Action 2.1.1.1**: Design dashboard endpoint contract
- **Scope**: Document `/api/v1/dashboard` response: `{ stats, recent_activity, library_preview }`
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Contract documented
- **Rollback**: N/A (documentation)
- [ ] **Action 2.1.1.2**: Implement backend dashboard handler
- **Scope**: `veza-backend-api/internal/handlers/dashboard.go` (create)
- **Dependencies**: Action 2.1.1.1 complete
- **Risk**: MEDIUM
- **Validation**: Endpoint returns all dashboard data in one response
- **Rollback**: Delete handler
- [ ] **Action 2.1.1.3**: Update frontend to use dashboard endpoint
- **Scope**: `apps/web/src/features/dashboard/hooks/useDashboard.ts` - Replace multiple calls with one
- **Dependencies**: Action 2.1.1.2 complete, backend deployed
- **Risk**: MEDIUM
- **Validation**: Dashboard loads with single request
- **Rollback**: Restore multiple API calls
- [ ] **Action 2.1.1.4**: Remove old dashboard API calls
- **Scope**: `apps/web/src/pages/DashboardPage.tsx:26` - Remove `fetchItems({ limit: 5 })` call
- **Dependencies**: Action 2.1.1.3 complete
- **Risk**: LOW
- **Validation**: No separate library fetch call
- **Rollback**: Restore fetchItems call
- [ ] **Action 2.1.1.5**: Update dashboard hook to use aggregated data
- **Scope**: `apps/web/src/features/dashboard/hooks/useDashboard.ts` - Map aggregated response to hook return
- **Dependencies**: Action 2.1.1.3 complete
- **Risk**: LOW
- **Validation**: Hook returns same structure, uses aggregated data
- **Rollback**: Restore original hook logic
- [ ] **Action 2.1.1.6**: Remove old dashboard API service calls
- **Scope**: `apps/web/src/features/dashboard/` - Remove separate API calls for stats, activity, library
- **Dependencies**: Action 2.1.1.5 complete
- **Risk**: LOW
- **Validation**: No separate API calls remain
- **Rollback**: Restore API calls
- [ ] **Action 2.1.1.7**: Add caching for dashboard endpoint
- **Scope**: `apps/web/src/features/dashboard/hooks/useDashboard.ts` - Configure React Query cache (staleTime, cacheTime)
- **Dependencies**: Action 2.1.1.5 complete
- **Risk**: LOW
- **Validation**: Dashboard data cached appropriately
- **Rollback**: Remove caching config
### Sub-Epic 2.2: Server-Side Filtering Only 🟡
#### Task 2.2.1: Remove Client-Side Filtering
- [ ] **Action 2.2.1.1**: Remove client-side filter logic from LibraryPage
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:111-114` - Remove `useMemo` filtering
- **Dependencies**: Verify backend handles all filters
- **Risk**: MEDIUM
- **Validation**: No client-side filtering, backend returns filtered results
- **Rollback**: Restore `useMemo` logic
- [ ] **Action 2.2.1.2**: Ensure backend handles all filter params
- **Scope**: `veza-backend-api/internal/handlers/tracks.go` - Verify search, genre, format, sort handled
- **Dependencies**: Action 2.2.1.1 complete
- **Risk**: LOW
- **Validation**: All filter combinations work server-side
- **Rollback**: N/A (backend verification)
- [ ] **Action 2.2.1.3**: Handle LibraryPage.tsx vs LibraryPagePremium.tsx duplication
- **Scope**: Audit both files - Determine which is active, consolidate or remove duplicate
- **Dependencies**: None
- **Risk**: MEDIUM (may break routing)
- **Validation**: Single LibraryPage file, routing works
- **Rollback**: Restore both files
- [ ] **Action 2.2.1.4**: Verify LibraryPage.tsx.old is not imported
- **Scope**: Search codebase for imports of LibraryPage.tsx.old - Verify no references
- **Dependencies**: Action 2.2.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: No imports found
- **Rollback**: N/A (verification)
- [ ] **Action 2.2.1.5**: Remove LibraryPage.tsx.old if obsolete
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx.old` - Delete if not needed
- **Dependencies**: Action 2.2.1.4 complete
- **Risk**: LOW
- **Validation**: File deleted, no references
- **Rollback**: Restore from git
### Sub-Epic 2.3: Unified Cache Invalidation 🟡
#### Task 2.3.1: Sync React Query Cache Across Tabs
- [ ] **Action 2.3.1.1**: Create React Query sync utility
- **Scope**: `apps/web/src/utils/reactQuerySync.ts` (create) - Use BroadcastChannel
- **Dependencies**: None
- **Risk**: MEDIUM
- **Validation**: Cache updates sync across tabs
- **Rollback**: Delete utility
- [ ] **Action 2.3.1.2**: Integrate sync into query client setup
- **Scope**: `apps/web/src/app/App.tsx` - Initialize sync on mount
- **Dependencies**: Action 2.3.1.1 complete
- **Risk**: LOW
- **Validation**: Multi-tab updates work
- **Rollback**: Remove initialization
- [ ] **Action 2.3.1.3**: Handle broadcastSync message conflicts
- **Scope**: `apps/web/src/utils/broadcastSync.ts:72-279` - Ensure React Query sync doesn't conflict with Zustand sync
- **Dependencies**: Action 2.3.1.1 complete
- **Risk**: MEDIUM
- **Validation**: Both syncs work without conflicts
- **Rollback**: Remove React Query sync
- [ ] **Action 2.3.1.4**: Add message deduplication for React Query sync
- **Scope**: `apps/web/src/utils/reactQuerySync.ts` - Use message IDs to prevent duplicate processing
- **Dependencies**: Action 2.3.1.1 complete
- **Risk**: LOW
- **Validation**: No duplicate cache updates
- **Rollback**: Remove deduplication
### Sub-Epic 2.5: Audit API Client Utilities 🟢
#### Task 2.5.1: Verify API Client Utilities
- [ ] **Action 2.5.1.1**: Audit requestDeduplication utility
- **Scope**: `apps/web/src/services/requestDeduplication.ts` - Verify it works correctly, document usage
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Utility documented, works correctly
- **Rollback**: N/A (audit)
- [ ] **Action 2.5.1.2**: Audit responseCache utility
- **Scope**: `apps/web/src/services/responseCache.ts` - Verify it works correctly, document usage
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Utility documented, works correctly
- **Rollback**: N/A (audit)
- [ ] **Action 2.5.1.3**: Audit offlineQueue utility
- **Scope**: `apps/web/src/services/offlineQueue.ts` - Verify it works correctly, document usage
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Utility documented, works correctly
- **Rollback**: N/A (audit)
- [ ] **Action 2.5.1.4**: Add UI for offline queue management
- **Scope**: `apps/web/src/components/OfflineQueueManager.tsx` (create) - Show queued requests, allow retry/cancel
- **Dependencies**: Action 2.5.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: UI shows queued requests
- **Rollback**: Delete component
- [ ] **Action 2.5.1.5**: Integrate offline queue UI with OfflineIndicator
- **Scope**: `apps/web/src/components/OfflineIndicator.tsx` - Show queue status, link to manager
- **Dependencies**: Action 2.5.1.4 complete
- **Risk**: LOW 🔒
- **Validation**: Indicator shows queue status
- **Rollback**: Remove queue status
- [ ] **Action 2.5.1.6**: Test request deduplication works correctly
- **Scope**: `apps/web/src/services/requestDeduplication.ts` - Add tests or manual verification
- **Dependencies**: Action 2.5.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Deduplication works, no duplicate requests
- **Rollback**: N/A (testing)
- [ ] **Action 2.5.1.7**: Test response cache works correctly
- **Scope**: `apps/web/src/services/responseCache.ts` - Add tests or manual verification
- **Dependencies**: Action 2.5.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Cache works, responses cached correctly
- **Rollback**: N/A (testing)
- [ ] **Action 2.5.1.8**: Test offline queue works correctly
- **Scope**: `apps/web/src/services/offlineQueue.ts` - Add tests or manual verification
- **Dependencies**: Action 2.5.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: Queue works, requests queued when offline
- **Rollback**: N/A (testing)
- [ ] **Action 2.5.1.9**: Add cache invalidation for response cache
- **Scope**: `apps/web/src/services/responseCache.ts` - Ensure cache invalidated on mutations
- **Dependencies**: Action 2.5.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Cache invalidated correctly
- **Rollback**: Remove invalidation
- [ ] **Action 2.5.1.10**: Add cache size limits
- **Scope**: `apps/web/src/services/responseCache.ts` - Limit cache size, evict old entries
- **Dependencies**: Action 2.5.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Cache size limited
- **Rollback**: Remove limits
### Sub-Epic 2.4: Request Debouncing 🟢
#### Task 2.4.1: Add Debounce to Search Inputs
- [ ] **Action 2.4.1.1**: Install `use-debounce` or implement custom hook
- **Scope**: `apps/web/package.json` - Add dependency (if using library)
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Package installed
- **Rollback**: Remove from package.json
- [ ] **Action 2.4.1.2**: Add debounce to LibraryPage search
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:322-327` - Debounce `setSearchTerm`
- **Dependencies**: Action 2.4.1.1 complete
- **Risk**: LOW
- **Validation**: Search fires 300ms after typing stops
- **Rollback**: Remove debounce
- [ ] **Action 2.4.1.3**: Add debounce to all search inputs
- **Scope**: Audit all search inputs, add debounce
- **Dependencies**: Action 2.4.1.2 complete
- **Risk**: LOW
- **Validation**: All searches debounced
- **Rollback**: Remove debounce from each
- [ ] **Action 2.4.1.4**: Fix race condition in LibraryPage search/page reset
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:116-120` - Use debounced search term for page reset
- **Dependencies**: Action 2.4.1.2 complete
- **Risk**: LOW
- **Validation**: Page resets only after debounce completes
- **Rollback**: Restore original useEffect
---
## EPIC 3: ERROR PROPAGATION 🟡
**Priority**: CORRECTNESS SECOND
**Goal**: Standardize error display, improve recovery, reduce cognitive load
### Sub-Epic 3.1: Standard Error Component 🟡
#### Task 3.1.1: Create ErrorDisplay Component
- [ ] **Action 3.1.1.1**: Design ErrorDisplay component API
- **Scope**: Document props: `error`, `onRetry`, `showDetails`, `context`
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: API documented
- **Rollback**: N/A (documentation)
- [ ] **Action 3.1.1.2**: Implement ErrorDisplay component
- **Scope**: `apps/web/src/components/ui/ErrorDisplay.tsx` (create)
- **Dependencies**: Action 3.1.1.1 complete
- **Risk**: LOW
- **Validation**: Component renders errors with retry button
- **Rollback**: Delete component
- [ ] **Action 3.1.1.3**: Replace toast errors with ErrorDisplay in LibraryPage
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:141-144` - Replace toast with ErrorDisplay
- **Dependencies**: Action 3.1.1.2 complete
- **Risk**: MEDIUM
- **Validation**: Errors show inline, not toast
- **Rollback**: Restore toast
- [ ] **Action 3.1.1.4**: Audit all error display patterns
- **Scope**: Search codebase for `toast.error`, `toast.error()`, inline error divs - Document all patterns
- **Dependencies**: Action 3.1.1.3 complete
- **Risk**: LOW
- **Validation**: Complete list of error display locations
- **Rollback**: N/A (audit)
- [ ] **Action 3.1.1.5**: Create error display strategy document
- **Scope**: `apps/web/src/components/ui/ERROR_DISPLAY_STRATEGY.md` (create) - Document when to use toast vs ErrorDisplay
- **Dependencies**: Action 3.1.1.4 complete
- **Risk**: LOW
- **Validation**: Strategy documented
- **Rollback**: Delete file
- [ ] **Action 3.1.1.6**: Replace all toast.error() calls with ErrorDisplay (where appropriate)
- **Scope**: All locations from Action 3.1.1.4 - Replace based on strategy
- **Dependencies**: Action 3.1.1.5 complete
- **Risk**: MEDIUM
- **Validation**: Consistent error display across app
- **Rollback**: Restore toast calls
- [ ] **Action 3.1.1.7**: Remove duplicate error displays
- **Scope**: Components showing both toast and inline error - Remove duplicates
- **Dependencies**: Action 3.1.1.6 complete
- **Risk**: LOW
- **Validation**: No duplicate error displays
- **Rollback**: Restore duplicates
- [ ] **Action 3.1.1.8**: Update error display in AuthErrorMessage component
- **Scope**: `apps/web/src/features/auth/components/AuthErrorMessage.tsx` - Use ErrorDisplay if appropriate
- **Dependencies**: Action 3.1.1.2 complete
- **Risk**: LOW
- **Validation**: Auth errors use ErrorDisplay or consistent pattern
- **Rollback**: Restore original component
- [ ] **Action 3.1.1.9**: Update error display in PlayerError component
- **Scope**: `apps/web/src/features/player/components/PlayerError.tsx` - Use ErrorDisplay if appropriate
- **Dependencies**: Action 3.1.1.2 complete
- **Risk**: LOW
- **Validation**: Player errors use ErrorDisplay or consistent pattern
- **Rollback**: Restore original component
- [ ] **Action 3.1.1.10**: Update error display in PlaylistErrorBoundary
- **Scope**: `apps/web/src/features/playlists/components/PlaylistErrorBoundary.tsx` - Use ErrorDisplay
- **Dependencies**: Action 3.1.1.2 complete
- **Risk**: LOW
- **Validation**: Playlist errors use ErrorDisplay
- **Rollback**: Restore original component
### Sub-Epic 3.2: Error Categories 🟡
#### Task 3.2.1: Implement Error Categorization
- [ ] **Action 3.2.1.1**: Add error category detection
- **Scope**: `apps/web/src/utils/apiErrorHandler.ts` - Add `getErrorCategory()` function
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Function categorizes errors correctly
- **Rollback**: Remove function
- [ ] **Action 3.2.1.2**: Network errors show offline indicator
- **Scope**: `apps/web/src/components/OfflineIndicator.tsx` - Show when network error
- **Dependencies**: Action 3.2.1.1 complete
- **Risk**: LOW
- **Validation**: Indicator appears on network errors
- **Rollback**: Remove indicator logic
- [ ] **Action 3.2.1.3**: Validation errors highlight fields
- **Scope**: Form components - Highlight invalid fields from error.details
- **Dependencies**: Action 3.2.1.1 complete
- **Risk**: MEDIUM
- **Validation**: Invalid fields highlighted
- **Rollback**: Remove highlighting
- [ ] **Action 3.2.1.4**: Auth errors redirect to login
- **Scope**: `apps/web/src/services/api/client.ts` - Intercept 401, redirect
- **Dependencies**: Action 3.2.1.1 complete
- **Risk**: LOW
- **Validation**: 401 errors redirect
- **Rollback**: Remove redirect logic
- [ ] **Action 3.2.1.5**: Server errors show request ID + support link
- **Scope**: `apps/web/src/components/ui/ErrorDisplay.tsx` - Show request ID, add "Report Issue" button
- **Dependencies**: Action 3.1.1.2 complete
- **Risk**: LOW
- **Validation**: Request ID visible, support link works
- **Rollback**: Remove request ID display
- [ ] **Action 3.2.1.6**: Create support issue reporting utility
- **Scope**: `apps/web/src/utils/reportIssue.ts` (create) - Format issue with request ID, error details
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Utility formats issue report correctly
- **Rollback**: Delete utility
- [ ] **Action 3.2.1.7**: Integrate issue reporting with ErrorDisplay
- **Scope**: `apps/web/src/components/ui/ErrorDisplay.tsx` - Use reportIssue utility
- **Dependencies**: Action 3.2.1.6 complete
- **Risk**: LOW
- **Validation**: "Report Issue" button uses utility
- **Rollback**: Remove integration
### Sub-Epic 3.3: Error Boundaries 🟢
#### Task 3.3.1: Wrap Routes in Error Boundaries
- [ ] **Action 3.3.1.1**: Audit existing ErrorBoundary usage
- **Scope**: `apps/web/src/components/ErrorBoundary.tsx` - Check where used
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: List of routes without boundaries
- **Rollback**: N/A (read-only)
- [ ] **Action 3.3.1.2**: Wrap all routes in ErrorBoundary
- **Scope**: `apps/web/src/app/App.tsx` or router config - Add ErrorBoundary to each route
- **Dependencies**: Action 3.3.1.1 complete
- **Risk**: LOW
- **Validation**: All routes have error boundaries
- **Rollback**: Remove boundaries
- [ ] **Action 3.3.1.3**: Update ErrorBoundary to use ErrorDisplay
- **Scope**: `apps/web/src/components/ErrorBoundary.tsx` - Use ErrorDisplay component for rendering
- **Dependencies**: Action 3.1.1.2 complete
- **Risk**: LOW
- **Validation**: ErrorBoundary uses ErrorDisplay
- **Rollback**: Restore original ErrorBoundary rendering
- [ ] **Action 3.3.1.4**: Add error boundary logging
- **Scope**: `apps/web/src/components/ErrorBoundary.tsx` - Log errors to monitoring service
- **Dependencies**: Action 3.3.1.2 complete
- **Risk**: LOW
- **Validation**: Errors logged to monitoring
- **Rollback**: Remove logging
### Sub-Epic 3.4: Retry Logic 🟢
#### Task 3.4.1: Add Retry UI to Error States
- [ ] **Action 3.4.1.1**: Add retry button to ErrorDisplay
- **Scope**: `apps/web/src/components/ui/ErrorDisplay.tsx` - Add retry button, call `onRetry`
- **Dependencies**: Action 3.1.1.2 complete
- **Risk**: LOW
- **Validation**: Retry button works
- **Rollback**: Remove button
- [ ] **Action 3.4.1.2**: Audit all mutation error handlers
- **Scope**: Search for mutation error handlers - List all mutation error handlers
- **Dependencies**: Action 3.4.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Complete list of mutation error handlers
- **Rollback**: N/A (audit)
- [ ] **Action 3.4.1.3**: Implement retry for failed mutations
- **Scope**: All handlers from Action 3.4.1.2 - Add retry logic
- **Dependencies**: Action 3.4.1.2 complete
- **Risk**: MEDIUM
- **Validation**: Failed mutations can be retried
- **Rollback**: Remove retry logic
- [ ] **Action 3.4.1.4**: Add retry count limit
- **Scope**: Retry logic - Limit retry attempts (max 3)
- **Dependencies**: Action 3.4.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: Retries limited to 3 attempts
- **Rollback**: Remove limit
### Sub-Epic 3.5: Improve Network Error Messages 🟢
#### Task 3.5.1: Distinguish Network Error Types
- [ ] **Action 3.5.1.1**: Enhance network error detection
- **Scope**: `apps/web/src/utils/apiErrorHandler.ts:108-122` - Distinguish timeout vs connection refused vs offline
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Different messages for different error types
- **Rollback**: Restore generic message
- [ ] **Action 3.5.1.2**: Add offline detection utility
- **Scope**: `apps/web/src/utils/offlineDetection.ts` (create) - Use navigator.onLine API
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Utility detects online/offline state
- **Rollback**: Delete utility
- [ ] **Action 3.5.1.3**: Integrate offline detection with error handler
- **Scope**: `apps/web/src/utils/apiErrorHandler.ts` - Use offline detection for network errors
- **Dependencies**: Action 3.5.1.2 complete
- **Risk**: LOW
- **Validation**: Errors distinguish offline vs server down
- **Rollback**: Remove offline detection integration
---
## EPIC 4: STATE OWNERSHIP 🟡
**Priority**: CORRECTNESS SECOND
**Goal**: Single source of truth, eliminate duplication, prevent desync
### Sub-Epic 4.1: Migrate Domain Data to React Query 🟡
#### Task 4.1.1: Remove User from Zustand Auth Store
- [ ] **Action 4.1.1.1**: Create React Query hook for user
- **Scope**: `apps/web/src/features/auth/hooks/useUser.ts` (create) - `useQuery(['user', 'me'], getMe)`
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Hook returns user data
- **Rollback**: Delete hook
- [ ] **Action 4.1.1.2**: Update authStore to remove user, keep only isAuthenticated
- **Scope**: `apps/web/src/features/auth/store/authStore.ts` - Remove `user` field, keep boolean
- **Dependencies**: Action 4.1.1.1 complete
- **Risk**: HIGH (breaking change)
- **Validation**: Store only has `isAuthenticated`, no `user`
- **Rollback**: Restore `user` field
- [ ] **Action 4.1.1.3**: Audit all files using `useAuthStore().user`
- **Scope**: Search codebase for `useAuthStore().user`, `useAuthStore.getState().user`, document all locations
- **Dependencies**: Action 4.1.1.2 complete
- **Risk**: LOW
- **Validation**: Complete list of files using user from store
- **Rollback**: N/A (audit)
- [ ] **Action 4.1.1.4**: Replace all `useAuthStore().user` with `useUser()`
- **Scope**: All files from Action 4.1.1.3 - Replace with `useUser()` hook
- **Dependencies**: Action 4.1.1.3 complete
- **Risk**: HIGH
- **Validation**: No references to `useAuthStore().user`, all use `useUser()`
- **Rollback**: Restore references
- [ ] **Action 4.1.1.5**: Update components that destructure user from store
- **Scope**: Components using `const { user } = useAuthStore()` - Update to use hook
- **Dependencies**: Action 4.1.1.4 complete
- **Risk**: MEDIUM
- **Validation**: All destructuring updated
- **Rollback**: Restore destructuring
#### Task 4.1.2: Remove Tracks from Zustand Library Store
- [ ] **Action 4.1.2.1**: Verify React Query handles all track queries
- **Scope**: Audit `apps/web/src/features/tracks/` - Ensure all queries use React Query
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: All track data from React Query
- **Rollback**: N/A (verification)
- [ ] **Action 4.1.2.2**: Audit library store for all domain data
- **Scope**: `apps/web/src/stores/library.ts` - List all fields: `items`, `favorites`, `pagination`, `filters`
- **Dependencies**: Action 4.1.2.1 complete
- **Risk**: LOW
- **Validation**: Complete list of domain data fields
- **Rollback**: N/A (audit)
- [ ] **Action 4.1.2.3**: Determine which fields are UI state vs domain data
- **Scope**: `apps/web/src/stores/library.ts` - Categorize: UI state (filters, view preferences) vs domain (items, favorites)
- **Dependencies**: Action 4.1.2.2 complete
- **Risk**: LOW
- **Validation**: Fields categorized
- **Rollback**: N/A (categorization)
- [ ] **Action 4.1.2.4**: Remove domain data from library store
- **Scope**: `apps/web/src/stores/library.ts` - Remove `items`, `favorites`, `pagination`, keep only `filters` (UI state)
- **Dependencies**: Action 4.1.2.3 complete, React Query handles all domain data
- **Risk**: HIGH
- **Validation**: Store has no domain data, only UI state
- **Rollback**: Restore domain data fields
- [ ] **Action 4.1.2.5**: Remove undoRedo middleware from library store
- **Scope**: `apps/web/src/stores/library.ts:64` - Remove `undoRedo()` wrapper
- **Dependencies**: Action 4.1.2.4 complete (no domain data to undo)
- **Risk**: MEDIUM
- **Validation**: No undoRedo middleware
- **Rollback**: Restore undoRedo wrapper
- [ ] **Action 4.1.2.6**: Remove stateNormalization from library store
- **Scope**: `apps/web/src/stores/library.ts` - Remove normalized state, use React Query normalization
- **Dependencies**: Action 4.1.2.4 complete
- **Risk**: MEDIUM
- **Validation**: No normalization utilities used
- **Rollback**: Restore normalization
- [ ] **Action 4.1.2.7**: Remove stateMiddleware from library store
- **Scope**: `apps/web/src/stores/library.ts:65` - Remove `stateMiddleware()` wrapper
- **Dependencies**: Action 4.1.2.4 complete
- **Risk**: MEDIUM
- **Validation**: No stateMiddleware wrapper
- **Rollback**: Restore stateMiddleware
- [ ] **Action 4.1.2.8**: Update all components using library store domain data
- **Scope**: All components using `useLibraryStore().items`, `.favorites`, `.pagination` - Replace with React Query
- **Dependencies**: Action 4.1.2.4 complete
- **Risk**: HIGH
- **Validation**: No components access domain data from store
- **Rollback**: Restore store access
### Sub-Epic 4.2: Unified Cache Invalidation 🟢
#### Task 4.2.1: Sync React Query Cache with BroadcastChannel
- [ ] **Action 4.2.1.1**: Extend broadcastSync to invalidate React Query
- **Scope**: `apps/web/src/utils/broadcastSync.ts` - Add React Query invalidation on state update
- **Dependencies**: Action 2.3.1.1 complete
- **Risk**: MEDIUM
- **Validation**: Zustand updates trigger React Query invalidation
- **Rollback**: Remove invalidation logic
### Sub-Epic 4.3: Simplify Auth State 🟢
#### Task 4.3.1: Remove Complex Deduplication Logic
- [ ] **Action 4.3.1.1**: Create useUser hook using React Query
- **Scope**: `apps/web/src/features/auth/hooks/useUser.ts` - Use `useQuery(['user', 'me'], getMe)`
- **Dependencies**: Action 4.1.1.1 complete
- **Risk**: LOW
- **Validation**: Hook uses React Query, has built-in deduplication
- **Rollback**: Delete hook
- [ ] **Action 4.3.1.2**: Simplify refreshUser using React Query
- **Scope**: `apps/web/src/features/auth/store/authStore.ts:142-218` - Remove manual deduplication, use React Query hook
- **Dependencies**: Action 4.3.1.1 complete
- **Risk**: MEDIUM
- **Validation**: No manual promise deduplication needed
- **Rollback**: Restore deduplication logic
- [ ] **Action 4.3.1.3**: Remove _refreshUserPromise field
- **Scope**: `apps/web/src/features/auth/store/authStore.ts:20` - Remove field, no longer needed
- **Dependencies**: Action 4.3.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Field removed, no references
- **Rollback**: Restore field
### Sub-Epic 4.4: Standardize Optimistic Updates 🟢
#### Task 4.4.1: Use React Query's onMutate
- [ ] **Action 4.4.1.1**: Audit custom optimistic updates
- **Scope**: `apps/web/src/utils/optimisticStoreUpdates.ts` - List all optimistic logic
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: List of optimistic updates
- **Rollback**: N/A (audit)
- [ ] **Action 4.4.1.2**: Migrate to React Query's onMutate
- **Scope**: All mutations - Use `onMutate` instead of custom logic
- **Dependencies**: Action 4.4.1.1 complete
- **Risk**: MEDIUM
- **Validation**: All optimistic updates use React Query
- **Rollback**: Restore custom logic
- [ ] **Action 4.4.1.3**: Delete optimisticStoreUpdates.ts
- **Scope**: Delete `apps/web/src/utils/optimisticStoreUpdates.ts`
- **Dependencies**: Action 4.4.1.2 complete
- **Risk**: LOW
- **Validation**: File deleted, no imports
- **Rollback**: Restore from git
- [ ] **Action 4.4.1.4**: Audit all mutations for optimistic updates
- **Scope**: Search codebase for mutations - List all mutations, check which have optimistic updates
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Complete list of mutations with optimistic status
- **Rollback**: N/A (audit)
- [ ] **Action 4.4.1.5**: Add optimistic updates to mutations missing them
- **Scope**: Mutations without optimistic updates - Add onMutate logic
- **Dependencies**: Action 4.4.1.4 complete
- **Risk**: MEDIUM
- **Validation**: All mutations have optimistic updates
- **Rollback**: Remove optimistic updates
### Sub-Epic 4.5: Audit All Zustand Stores 🟡
#### Task 4.5.1: Audit stores for domain data
- [ ] **Action 4.5.1.1**: List all Zustand stores
- **Scope**: Search for `create<` in `apps/web/src/stores/` and `apps/web/src/features/*/store/` - List all stores
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Complete list of all stores
- **Rollback**: N/A (audit)
- [ ] **Action 4.5.1.2**: Categorize stores: UI state vs domain data
- **Scope**: All stores from Action 4.5.1.1 - Categorize each store
- **Dependencies**: Action 4.5.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: All stores categorized
- **Rollback**: N/A (categorization)
- [ ] **Action 4.5.1.3**: Check for stores/auth.ts (should be removed)
- **Scope**: `apps/web/src/stores/auth.ts` (if exists) - Verify it's obsolete
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: File doesn't exist or is unused
- **Rollback**: N/A (verification)
- [ ] **Action 4.5.1.4**: Remove stores/auth.ts if obsolete
- **Scope**: `apps/web/src/stores/auth.ts` - Delete if unused
- **Dependencies**: Action 4.5.1.3 complete, verify no imports
- **Risk**: MEDIUM
- **Validation**: File deleted, no imports remain
- **Rollback**: Restore from git
- [ ] **Action 4.5.1.5**: Handle stores/chat.ts vs features/chat/store/chatStore.ts duplication
- **Scope**: Both files - Determine which is active, consolidate or remove duplicate
- **Dependencies**: Action 4.5.1.1 complete
- **Risk**: MEDIUM (may break chat functionality)
- **Validation**: Single chat store, chat works
- **Rollback**: Restore both files
- [ ] **Action 4.5.1.6**: Audit cartStore for domain data
- **Scope**: `apps/web/src/stores/cartStore.ts` - Check if stores domain data (cart items)
- **Dependencies**: Action 4.5.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Cart store categorized
- **Rollback**: N/A (audit)
- [ ] **Action 4.5.1.7**: Migrate cartStore domain data to React Query (if needed)
- **Scope**: `apps/web/src/stores/cartStore.ts` - Move cart items to React Query if domain data
- **Dependencies**: Action 4.5.1.6 complete
- **Risk**: MEDIUM
- **Validation**: Cart items in React Query, store only UI state
- **Rollback**: Restore cart items to store
- [ ] **Action 4.5.1.8**: Audit playerStore for domain data
- **Scope**: `apps/web/src/features/player/store/playerStore.ts` - Check if stores domain data
- **Dependencies**: Action 4.5.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Player store categorized
- **Rollback**: N/A (audit)
- [ ] **Action 4.5.1.9**: Migrate playerStore domain data to React Query (if needed)
- **Scope**: `apps/web/src/features/player/store/playerStore.ts` - Move domain data to React Query
- **Dependencies**: Action 4.5.1.8 complete
- **Risk**: MEDIUM
- **Validation**: Domain data in React Query, store only player UI state
- **Rollback**: Restore domain data to store
- [ ] **Action 4.5.1.10**: Verify uiStore only has UI state
- **Scope**: `apps/web/src/stores/ui.ts` - Verify only UI preferences (theme, language, sidebar)
- **Dependencies**: Action 4.5.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: UI store has no domain data
- **Rollback**: N/A (verification)
### Sub-Epic 4.6: Clean Up State Utilities 🟢
#### Task 4.6.1: Audit state utility files
- [ ] **Action 4.6.1.1**: List all state utility files
- **Scope**: `apps/web/src/utils/state*.ts`, `apps/web/src/utils/*state*.ts` - List all utilities
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Complete list of state utilities
- **Rollback**: N/A (audit)
- [ ] **Action 4.6.1.2**: Determine which utilities are still needed
- **Scope**: All utilities from Action 4.6.1.1 - Categorize: needed, redundant, obsolete
- **Dependencies**: Action 4.6.1.1 complete, Epic 4 complete
- **Risk**: LOW 🔒
- **Validation**: Utilities categorized
- **Rollback**: N/A (categorization)
- [ ] **Action 4.6.1.3**: Remove obsolete state utilities
- **Scope**: Obsolete utilities from Action 4.6.1.2 - Delete unused files
- **Dependencies**: Action 4.6.1.2 complete, verify no imports
- **Risk**: MEDIUM
- **Validation**: Obsolete utilities deleted, no imports
- **Rollback**: Restore from git
- [ ] **Action 4.6.1.4**: Simplify stateMiddleware if still needed
- **Scope**: `apps/web/src/utils/stateMiddleware.ts` - Simplify or remove if redundant
- **Dependencies**: Action 4.6.1.2 complete
- **Risk**: MEDIUM
- **Validation**: Middleware simplified or removed
- **Rollback**: Restore original middleware
- [ ] **Action 4.6.1.5**: Update stateInvalidation to work with React Query
- **Scope**: `apps/web/src/utils/stateInvalidation.ts` - Update to invalidate React Query cache
- **Dependencies**: Epic 4 complete
- **Risk**: MEDIUM
- **Validation**: Invalidation works with React Query
- **Rollback**: Restore original invalidation
- [ ] **Action 4.6.1.6**: Update statePersistence if still needed
- **Scope**: `apps/web/src/utils/statePersistence.ts` - Ensure it doesn't conflict with React Query persistence
- **Dependencies**: Epic 4 complete
- **Risk**: MEDIUM
- **Validation**: No conflicts with React Query
- **Rollback**: Restore original persistence
- [ ] **Action 4.6.1.7**: Update STATE_DEBUGGING.md documentation
- **Scope**: `apps/web/src/docs/STATE_DEBUGGING.md` - Remove references to stores/auth.ts, update store list
- **Dependencies**: Action 4.5.1.4 complete
- **Risk**: LOW 🔒
- **Validation**: Documentation accurate
- **Rollback**: Restore original documentation
- [ ] **Action 4.6.1.8**: Update STATE_SELECTORS.md documentation
- **Scope**: `apps/web/src/docs/STATE_SELECTORS.md` - Update selectors for new store structure
- **Dependencies**: Epic 4 complete
- **Risk**: LOW 🔒
- **Validation**: Documentation accurate
- **Rollback**: Restore original documentation
- [ ] **Action 4.6.1.9**: Audit undoRedo utility usage
- **Scope**: `apps/web/src/utils/undoRedo.ts` - Check where used, determine if still needed
- **Dependencies**: Action 4.1.2.5 complete
- **Risk**: LOW 🔒
- **Validation**: Usage documented
- **Rollback**: N/A (audit)
- [ ] **Action 4.6.1.10**: Remove undoRedo if unused
- **Scope**: `apps/web/src/utils/undoRedo.ts` - Delete if no longer used
- **Dependencies**: Action 4.6.1.9 complete, verify no imports
- **Risk**: MEDIUM
- **Validation**: File deleted, no imports
- **Rollback**: Restore from git
- [ ] **Action 4.6.1.11**: Audit stateNormalization utility
- **Scope**: `apps/web/src/utils/stateNormalization.ts` - Check if still needed with React Query
- **Dependencies**: Action 4.1.2.6 complete
- **Risk**: LOW 🔒
- **Validation**: Usage documented
- **Rollback**: N/A (audit)
- [ ] **Action 4.6.1.12**: Remove stateNormalization if unused
- **Scope**: `apps/web/src/utils/stateNormalization.ts` - Delete if no longer used
- **Dependencies**: Action 4.6.1.11 complete, verify no imports
- **Risk**: MEDIUM
- **Validation**: File deleted, no imports
- **Rollback**: Restore from git
- [ ] **Action 4.6.1.13**: Audit stateCleanup utility
- **Scope**: `apps/web/src/utils/stateCleanup.ts` - Check if still needed
- **Dependencies**: Epic 4 complete
- **Risk**: LOW 🔒
- **Validation**: Usage documented
- **Rollback**: N/A (audit)
- [ ] **Action 4.6.1.14**: Update or remove stateCleanup utility
- **Scope**: `apps/web/src/utils/stateCleanup.ts` - Update for React Query or remove if unused
- **Dependencies**: Action 4.6.1.13 complete
- **Risk**: MEDIUM
- **Validation**: Utility updated or removed
- **Rollback**: Restore original utility
---
## EPIC 5: SECURITY & ROBUSTNESS 🔴
**Priority**: STABILITY FIRST
**Goal**: Fix XSS vulnerabilities, improve error correlation, add rate limit UI
### Sub-Epic 5.1: Secure Token Storage 🔴
#### Task 5.1.1: Move Access Token to httpOnly Cookie
- [ ] **Action 5.1.1.1**: Backend: Set access token in httpOnly cookie
- **Scope**: `veza-backend-api/internal/handlers/auth.go` - Set cookie on login/refresh
- **Dependencies**: None
- **Risk**: HIGH (breaking change)
- **Validation**: Cookie set, accessible in browser
- **Rollback**: Remove cookie, restore token in response body
- [ ] **Action 5.1.1.2**: Frontend: Remove localStorage token storage
- **Scope**: `apps/web/src/services/tokenStorage.ts` - Remove localStorage, read from cookie
- **Dependencies**: Action 5.1.1.1 complete, backend deployed
- **Risk**: HIGH
- **Validation**: No tokens in localStorage, all from cookie
- **Rollback**: Restore localStorage
- [ ] **Action 5.1.1.3**: Update API client to read token from cookie
- **Scope**: `apps/web/src/services/api/client.ts` - Remove Authorization header, rely on cookie
- **Dependencies**: Action 5.1.1.2 complete
- **Risk**: MEDIUM
- **Validation**: Requests work without Authorization header
- **Rollback**: Restore header logic
**Alternative**: Short-lived tokens (5 min) + frequent refresh
- [ ] **Action 5.1.1.4**: Reduce access token expiry to 5 minutes
- **Scope**: `veza-backend-api/internal/services/jwt.go` - Change expiry
- **Dependencies**: None
- **Risk**: MEDIUM
- **Validation**: Tokens expire in 5 min
- **Rollback**: Restore original expiry
- [ ] **Action 5.1.1.5**: Implement proactive refresh every 4 minutes
- **Scope**: `apps/web/src/services/tokenRefresh.ts` - Refresh before expiry
- **Dependencies**: Action 5.1.1.4 complete
- **Risk**: LOW
- **Validation**: Tokens refresh automatically
- **Rollback**: Remove proactive refresh
- [ ] **Action 5.1.1.6**: Clean up localStorage token references
- **Scope**: Search codebase for `localStorage.getItem('access_token')`, `localStorage.setItem('access_token')` - Remove all
- **Dependencies**: Action 5.1.1.2 complete
- **Risk**: LOW
- **Validation**: No localStorage token access remains
- **Rollback**: Restore localStorage access
- [ ] **Action 5.1.1.7**: Update TokenStorage to read from cookie only
- **Scope**: `apps/web/src/services/tokenStorage.ts` - Remove localStorage, add cookie reading
- **Dependencies**: Action 5.1.1.2 complete
- **Risk**: MEDIUM
- **Validation**: TokenStorage reads from cookie, no localStorage
- **Rollback**: Restore localStorage logic
- [ ] **Action 5.1.1.8**: Update tokenRefresh to work with cookies
- **Scope**: `apps/web/src/services/tokenRefresh.ts` - Update to read/write cookies instead of localStorage
- **Dependencies**: Action 5.1.1.7 complete
- **Risk**: MEDIUM
- **Validation**: Token refresh works with cookies
- **Rollback**: Restore localStorage logic
- [ ] **Action 5.1.1.9**: Update all token access to use TokenStorage
- **Scope**: Search for direct localStorage token access - Replace with TokenStorage methods
- **Dependencies**: Action 5.1.1.7 complete
- **Risk**: MEDIUM
- **Validation**: No direct localStorage token access
- **Rollback**: Restore direct access
### Sub-Epic 5.2: Pre-Validation 🟢
#### Task 5.2.1: Add Backend Validation Endpoint
- [ ] **Action 5.2.1.1**: Create `/api/v1/validate` endpoint
- **Scope**: `veza-backend-api/internal/handlers/validate.go` (create)
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Endpoint validates request bodies
- **Rollback**: Delete endpoint
- [ ] **Action 5.2.1.2**: Frontend: Call validate before submit
- **Scope**: Form components - Call validate endpoint on blur/change
- **Dependencies**: Action 5.2.1.1 complete
- **Risk**: MEDIUM
- **Validation**: Backend errors shown before submit
- **Rollback**: Remove validation calls
- [ ] **Action 5.2.1.3**: Create useFormValidation hook
- **Scope**: `apps/web/src/hooks/useFormValidation.ts` (create) - Hook for pre-validation
- **Dependencies**: Action 5.2.1.1 complete
- **Risk**: LOW
- **Validation**: Hook works, integrates with forms
- **Rollback**: Delete hook
- [ ] **Action 5.2.1.4**: Integrate useFormValidation into all forms
- **Scope**: All form components - Use hook for pre-validation
- **Dependencies**: Action 5.2.1.3 complete
- **Risk**: MEDIUM
- **Validation**: All forms use pre-validation
- **Rollback**: Remove hook usage
- [ ] **Action 5.2.1.5**: Debounce validation calls
- **Scope**: `apps/web/src/hooks/useFormValidation.ts` - Debounce validation requests
- **Dependencies**: Action 5.2.1.3 complete
- **Risk**: LOW
- **Validation**: Validation debounced (300ms)
- **Rollback**: Remove debounce
### Sub-Epic 5.3: Error Correlation 🟢
#### Task 5.3.1: Always Show Request ID
- [ ] **Action 5.3.1.1**: Remove dev-only check for request ID
- **Scope**: `apps/web/src/utils/apiErrorHandler.ts:315-320` - Always include request ID
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Request ID always shown
- **Rollback**: Restore dev check
- [ ] **Action 5.3.1.2**: Add "Report Issue" button with request ID
- **Scope**: `apps/web/src/components/ui/ErrorDisplay.tsx` - Add button, copy request ID
- **Dependencies**: Action 3.1.1.2 complete
- **Risk**: LOW
- **Validation**: Button copies request ID to clipboard
- **Rollback**: Remove button
### Sub-Epic 5.4: Rate Limit UI 🟢
#### Task 5.4.1: Display Rate Limit Status
- [ ] **Action 5.4.1.1**: Parse rate limit headers
- **Scope**: `apps/web/src/services/api/client.ts` - Parse `X-RateLimit-*` headers
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Headers parsed, stored in state
- **Rollback**: Remove parsing
- [ ] **Action 5.4.1.2**: Create rate limit indicator component
- **Scope**: `apps/web/src/components/RateLimitIndicator.tsx` (create)
- **Dependencies**: Action 5.4.1.1 complete
- **Risk**: LOW
- **Validation**: Component shows rate limit status
- **Rollback**: Delete component
- [ ] **Action 5.4.1.3**: Show indicator in header
- **Scope**: `apps/web/src/components/Header.tsx` or layout - Add RateLimitIndicator
- **Dependencies**: Action 5.4.1.2 complete
- **Risk**: LOW
- **Validation**: Indicator visible in header
- **Rollback**: Remove from header
- [ ] **Action 5.4.1.4**: Disable buttons when rate limited
- **Scope**: All mutation buttons - Check rate limit, disable if limited
- **Dependencies**: Action 5.4.1.1 complete
- **Risk**: MEDIUM
- **Validation**: Buttons disabled when rate limited
- **Rollback**: Remove disable logic
- [ ] **Action 5.4.1.5**: Show countdown timer
- **Scope**: `apps/web/src/components/RateLimitIndicator.tsx` - Calculate reset time, show timer
- **Dependencies**: Action 5.4.1.2 complete
- **Risk**: LOW
- **Validation**: Timer counts down to reset
- **Rollback**: Remove timer
- [ ] **Action 5.4.1.6**: Add rate limit state management
- **Scope**: `apps/web/src/stores/rateLimit.ts` (create) - Store rate limit state from headers
- **Dependencies**: Action 5.4.1.1 complete
- **Risk**: LOW
- **Validation**: Rate limit state stored and accessible
- **Rollback**: Delete store
- [ ] **Action 5.4.1.7**: Integrate rate limit store with indicator
- **Scope**: `apps/web/src/components/RateLimitIndicator.tsx` - Use rate limit store
- **Dependencies**: Action 5.4.1.6 complete
- **Risk**: LOW
- **Validation**: Indicator reads from store
- **Rollback**: Remove store integration
---
## EPIC 6: SCALABILITY & EVOLUTION 🟢
**Priority**: UX/UI THIRD
**Goal**: Reduce coupling, improve performance, enable evolution
### Sub-Epic 6.1: API Abstraction Layer 🟢
#### Task 6.1.1: Create Service Layer
- [ ] **Action 6.1.1.1**: Create tracks API service
- **Scope**: `apps/web/src/services/api/tracks.ts` (create) - Export `tracksApi` object
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Service exports list, get, create, update, delete methods
- **Rollback**: Delete file
- [ ] **Action 6.1.1.2**: Replace direct API calls with service
- **Scope**: All components importing `@/features/tracks/api/trackApi` - Use `tracksApi` instead
- **Dependencies**: Action 6.1.1.1 complete
- **Risk**: MEDIUM
- **Validation**: No direct API imports
- **Rollback**: Restore direct imports
- [ ] **Action 6.1.1.3**: Create users API service
- **Scope**: `apps/web/src/services/api/users.ts` (create) - Export `usersApi` object
- **Dependencies**: Action 6.1.1.1 complete
- **Risk**: LOW
- **Validation**: Service exports user-related methods
- **Rollback**: Delete file
- [ ] **Action 6.1.1.4**: Create playlists API service
- **Scope**: `apps/web/src/services/api/playlists.ts` (create) - Export `playlistsApi` object
- **Dependencies**: Action 6.1.1.1 complete
- **Risk**: LOW
- **Validation**: Service exports playlist-related methods
- **Rollback**: Delete file
- [ ] **Action 6.1.1.5**: Create auth API service
- **Scope**: `apps/web/src/services/api/auth.ts` (create/update) - Export `authApi` object
- **Dependencies**: Action 6.1.1.1 complete
- **Risk**: LOW
- **Validation**: Service exports auth-related methods
- **Rollback**: Restore original auth service
- [ ] **Action 6.1.1.6**: Replace direct API calls with services (users)
- **Scope**: All components importing user API functions - Use `usersApi` instead
- **Dependencies**: Action 6.1.1.3 complete
- **Risk**: MEDIUM
- **Validation**: No direct user API imports
- **Rollback**: Restore direct imports
- [ ] **Action 6.1.1.7**: Replace direct API calls with services (playlists)
- **Scope**: All components importing playlist API functions - Use `playlistsApi` instead
- **Dependencies**: Action 6.1.1.4 complete
- **Risk**: MEDIUM
- **Validation**: No direct playlist API imports
- **Rollback**: Restore direct imports
- [ ] **Action 6.1.1.8**: Replace direct API calls with services (auth)
- **Scope**: All components importing auth API functions - Use `authApi` instead
- **Dependencies**: Action 6.1.1.5 complete
- **Risk**: MEDIUM
- **Validation**: No direct auth API imports
- **Rollback**: Restore direct imports
- [ ] **Action 6.1.1.9**: Create index file for API services
- **Scope**: `apps/web/src/services/api/index.ts` (create/update) - Export all services
- **Dependencies**: All services created
- **Risk**: LOW
- **Validation**: All services exported from index
- **Rollback**: Delete index file
- [ ] **Action 6.1.1.10**: Update all feature API files to use services
- **Scope**: `apps/web/src/features/*/api/*.ts` - Update to use service layer
- **Dependencies**: All services created
- **Risk**: MEDIUM
- **Validation**: Feature APIs use service layer
- **Rollback**: Restore direct API calls
- [ ] **Action 6.1.1.11**: Remove obsolete feature API files (if any)
- **Scope**: Feature API files that are now redundant - Delete if replaced by services
- **Dependencies**: Action 6.1.1.10 complete
- **Risk**: MEDIUM
- **Validation**: Obsolete files deleted
- **Rollback**: Restore deleted files
### Sub-Epic 6.2: Code Splitting 🟢
#### Task 6.2.1: Lazy Load Routes
- [ ] **Action 6.2.1.1**: Convert routes to lazy loading
- **Scope**: Router config - Use `React.lazy()` for all routes
- **Dependencies**: None
- **Risk**: MEDIUM
- **Validation**: Routes load on demand, bundle size reduced
- **Rollback**: Remove lazy loading
- [ ] **Action 6.2.1.2**: Split vendor bundles
- **Scope**: `apps/web/vite.config.ts` - Configure manual chunks
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Vendor code split into separate chunks
- **Rollback**: Remove manual chunks
- [ ] **Action 6.2.1.3**: Identify heavy components
- **Scope**: Audit all components - List heavy components (charts, editors, large libraries)
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: List of heavy components
- **Rollback**: N/A (audit)
- [ ] **Action 6.2.1.4**: Dynamic imports for heavy components
- **Scope**: Heavy components from Action 6.2.1.3 - Use dynamic imports
- **Dependencies**: Action 6.2.1.3 complete
- **Risk**: LOW
- **Validation**: Heavy components load on demand
- **Rollback**: Restore static imports
- [ ] **Action 6.2.1.5**: Add loading states for lazy-loaded components
- **Scope**: All lazy-loaded components - Add Suspense boundaries with loading states
- **Dependencies**: Action 6.2.1.1 complete
- **Risk**: LOW
- **Validation**: Loading states show during lazy load
- **Rollback**: Remove loading states
- [ ] **Action 6.2.1.6**: Add error boundaries for lazy-loaded components
- **Scope**: All lazy-loaded components - Wrap in error boundaries
- **Dependencies**: Action 6.2.1.1 complete, Action 3.3.1.2 complete
- **Risk**: LOW
- **Validation**: Errors in lazy-loaded components caught
- **Rollback**: Remove error boundaries
- [ ] **Action 6.2.1.7**: Measure bundle size before/after code splitting
- **Scope**: Build process - Measure bundle sizes
- **Dependencies**: Action 6.2.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Bundle sizes measured and documented
- **Rollback**: N/A (measurement)
- [ ] **Action 6.2.1.8**: Optimize bundle sizes if needed
- **Scope**: Bundle analysis - Optimize if bundles still too large
- **Dependencies**: Action 6.2.1.7 complete
- **Risk**: MEDIUM
- **Validation**: Bundle sizes optimized
- **Rollback**: Restore original bundles
### Sub-Epic 6.3: Virtualization 🟢
#### Task 6.3.1: Implement List Virtualization
- [ ] **Action 6.3.1.1**: Install react-window or @tanstack/react-virtual
- **Scope**: `apps/web/package.json` - Add dependency
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Package installed
- **Rollback**: Remove from package.json
- [ ] **Action 6.3.1.2**: Virtualize LibraryPage track list
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx` - Wrap track list in virtualizer
- **Dependencies**: Action 6.3.1.1 complete
- **Risk**: MEDIUM
- **Validation**: Long lists render smoothly
- **Rollback**: Remove virtualization
- [ ] **Action 6.3.1.3**: Implement infinite scroll
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx` - Load more on scroll
- **Dependencies**: Action 6.3.1.2 complete
- **Risk**: MEDIUM
- **Validation**: Tracks load as user scrolls
- **Rollback**: Restore pagination
- [ ] **Action 6.3.1.4**: Add loading indicator for infinite scroll
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx` - Show loading at bottom when fetching more
- **Dependencies**: Action 6.3.1.3 complete
- **Risk**: LOW
- **Validation**: Loading indicator appears when fetching
- **Rollback**: Remove indicator
- [ ] **Action 6.3.1.5**: Handle infinite scroll edge cases
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx` - Handle end of list, errors, empty states
- **Dependencies**: Action 6.3.1.3 complete
- **Risk**: MEDIUM
- **Validation**: Edge cases handled gracefully
- **Rollback**: Remove edge case handling
---
## EPIC 7: VISUAL HIERARCHY 🟢
**Priority**: UX/UI THIRD
**Goal**: Establish focal points, reduce visual noise, guide user attention
### Sub-Epic 7.1: Typography System ✅ QUICK WIN
#### Task 7.1.1: Define Type Scale
- [ ] **Action 7.1.1.1**: Add type scale to design tokens
- **Scope**: `apps/web/src/styles/design-tokens.css` - Add `--text-xs` through `--text-4xl`
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: All sizes defined, values match spec
- **Rollback**: Remove CSS variables
- [ ] **Action 7.1.1.2**: Create Tailwind type utilities
- **Scope**: `apps/web/tailwind.config.ts` - Add text size utilities
- **Dependencies**: Action 7.1.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: `text-xs` through `text-4xl` classes work
- **Rollback**: Remove from config
- [ ] **Action 7.1.1.3**: Audit all text size classes
- **Scope**: Search for `text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `text-3xl`, `text-4xl` - List all
- **Dependencies**: Action 7.1.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Complete list of text size classes
- **Rollback**: N/A (audit)
- [ ] **Action 7.1.1.4**: Replace all text-* classes with scale
- **Scope**: All components from Action 7.1.1.3 - Replace with scale classes
- **Dependencies**: Action 7.1.1.3 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: All text uses scale, visual consistency
- **Rollback**: Restore original classes
- [ ] **Action 7.1.1.5**: Add ESLint rule to enforce type scale
- **Scope**: `.eslintrc.js` - Add rule to warn on non-scale text sizes
- **Dependencies**: Action 7.1.1.4 complete
- **Risk**: LOW 🔒
- **Validation**: ESLint warns on non-scale sizes
- **Rollback**: Remove rule
#### Task 7.1.2: Fix Heading Inconsistencies
- [ ] **Action 7.1.2.1**: Audit all h1 elements
- **Scope**: Search for `<h1` in all components - List all h1 elements and their sizes
- **Dependencies**: Action 7.1.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: Complete list of h1 elements
- **Rollback**: N/A (audit)
- [ ] **Action 7.1.2.2**: Standardize h1 across pages
- **Scope**: All h1 elements from Action 7.1.2.1 - Use same size (text-3xl)
- **Dependencies**: Action 7.1.2.1 complete
- **Risk**: LOW 🔒
- **Validation**: All h1 same size
- **Rollback**: Restore original sizes
- [ ] **Action 7.1.2.3**: Standardize h2-h6 elements
- **Scope**: All h2-h6 elements - Use consistent sizes from type scale
- **Dependencies**: Action 7.1.2.2 complete
- **Risk**: LOW 🔒
- **Validation**: All headings use type scale
- **Rollback**: Restore original sizes
- [ ] **Action 7.1.2.4**: Standardize paragraph text sizes
- **Scope**: All `<p>` elements - Use consistent sizes (text-base for body, text-sm for secondary)
- **Dependencies**: Action 7.1.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: All paragraphs use type scale
- **Rollback**: Restore original sizes
### Sub-Epic 7.2: Spacing System ✅ QUICK WIN
#### Task 7.2.1: Define Spacing Scale
- [ ] **Action 7.2.1.1**: Add spacing scale to design tokens
- **Scope**: `apps/web/src/styles/design-tokens.css` - Add `--spacing-xs` through `--spacing-xxl`
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: All spacing values defined
- **Rollback**: Remove CSS variables
- [ ] **Action 7.2.1.2**: Audit all spacing classes
- **Scope**: Search for `space-y-`, `space-x-`, `gap-`, `p-`, `m-`, `px-`, `py-`, `mx-`, `my-` - List all spacing usage
- **Dependencies**: Action 7.2.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Complete list of spacing classes
- **Rollback**: N/A (audit)
- [ ] **Action 7.2.1.3**: Replace inconsistent spacing
- **Scope**: All components from Action 7.2.1.2 - Replace with scale
- **Dependencies**: Action 7.2.1.2 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: Consistent spacing throughout
- **Rollback**: Restore original spacing
- [ ] **Action 7.2.1.4**: Add ESLint rule to enforce spacing scale
- **Scope**: `.eslintrc.js` - Add rule to warn on non-scale spacing
- **Dependencies**: Action 7.2.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: ESLint warns on non-scale spacing
- **Rollback**: Remove rule
- [ ] **Action 7.2.1.3**: Create spacing utility classes
- **Scope**: `apps/web/tailwind.config.ts` - Add spacing utilities if needed
- **Dependencies**: Action 7.2.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Spacing utilities available
- **Rollback**: Remove utilities
- [ ] **Action 7.2.1.4**: Document spacing usage
- **Scope**: `apps/web/src/styles/design-tokens.css` - Add comments for usage
- **Dependencies**: Action 7.2.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Documentation clear
- **Rollback**: Remove comments
- [ ] **Action 7.2.1.5**: Create SPACING_GUIDE.md
- **Scope**: `apps/web/src/styles/SPACING_GUIDE.md` (create) - Document spacing system usage
- **Dependencies**: Action 7.2.1.4 complete
- **Risk**: LOW 🔒
- **Validation**: Guide documents spacing usage
- **Rollback**: Delete file
### Sub-Epic 7.3: Establish Focal Points 🟢
#### Task 7.3.1: Redesign Dashboard Hierarchy
- [ ] **Action 7.3.1.1**: Make primary stat (tracks played) large and prominent
- **Scope**: `apps/web/src/pages/DashboardPage.tsx:132-164` - Increase size of first stat card
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Primary stat 2x size of others
- **Rollback**: Restore equal sizes
- [ ] **Action 7.3.1.2**: Reduce welcome message size/weight
- **Scope**: `apps/web/src/pages/DashboardPage.tsx:101` - Change `text-4xl` to `text-2xl`
- **Dependencies**: Action 7.1.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: Message smaller, less prominent
- **Rollback**: Restore original size
- [ ] **Action 7.3.1.3**: Make Upload button most prominent (FAB or large)
- **Scope**: `apps/web/src/pages/DashboardPage.tsx:119-127` - Increase size, add FAB styling
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Upload button most visible
- **Rollback**: Restore original styling
- [ ] **Action 7.3.1.4**: Collapse activity feed by default
- **Scope**: `apps/web/src/pages/DashboardPage.tsx:207-254` - Add collapsible wrapper
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Feed collapsed, expandable
- **Rollback**: Remove collapsible
- [ ] **Action 7.3.1.5**: Create Collapsible component (if doesn't exist)
- **Scope**: `apps/web/src/components/ui/collapsible.tsx` (create) - Reusable collapsible wrapper
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Component works, reusable
- **Rollback**: Delete component
- [ ] **Action 7.3.1.6**: Use Collapsible for activity feed
- **Scope**: `apps/web/src/pages/DashboardPage.tsx:207-254` - Wrap with Collapsible component
- **Dependencies**: Action 7.3.1.5 complete
- **Risk**: LOW 🔒
- **Validation**: Feed uses Collapsible component
- **Rollback**: Remove Collapsible wrapper
- [ ] **Action 7.3.1.7**: Add FAB (Floating Action Button) component
- **Scope**: `apps/web/src/components/ui/FAB.tsx` (create) - Floating action button component
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: FAB component works
- **Rollback**: Delete component
- [ ] **Action 7.3.1.8**: Use FAB for Upload button
- **Scope**: `apps/web/src/pages/DashboardPage.tsx:119-127` - Replace button with FAB
- **Dependencies**: Action 7.3.1.7 complete
- **Risk**: LOW 🔒
- **Validation**: Upload uses FAB
- **Rollback**: Restore button
### Sub-Epic 7.4: Eliminate Dead Zones 🟢
#### Task 7.4.1: Compact Filters
- [ ] **Action 7.4.1.1**: Create Sidebar component (if doesn't exist)
- **Scope**: `apps/web/src/components/ui/Sidebar.tsx` (create) - Reusable sidebar component
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Sidebar component works
- **Rollback**: Delete component
- [ ] **Action 7.4.1.2**: Move filters to sidebar or collapsible section
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:317-383` - Move to sidebar
- **Dependencies**: Action 7.4.1.1 complete
- **Risk**: MEDIUM (layout change)
- **Validation**: Filters in sidebar, main area for content
- **Rollback**: Restore full-width filters
- [ ] **Action 7.4.1.3**: Make sidebar collapsible
- **Scope**: `apps/web/src/components/ui/Sidebar.tsx` - Add collapse/expand functionality
- **Dependencies**: Action 7.4.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Sidebar collapses/expands
- **Rollback**: Remove collapse functionality
---
## EPIC 8: INTERACTION CLARITY 🟢
**Priority**: UX/UI THIRD
**Goal**: Make actions discoverable, provide feedback, reduce confusion
### Sub-Epic 8.1: Single Action Path 🟢
#### Task 8.1.1: Remove Duplicate Upload Buttons
- [ ] **Action 8.1.1.1**: Audit all upload buttons
- **Scope**: Search for "Upload" buttons, document locations
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: List of all upload buttons
- **Rollback**: N/A (audit)
- [ ] **Action 8.1.1.2**: Determine primary upload button location
- **Scope**: Based on Action 8.1.1.1 - Decide which location is primary (likely header/FAB)
- **Dependencies**: Action 8.1.1.1 complete
- **Risk**: LOW
- **Validation**: Primary location documented
- **Rollback**: N/A (decision)
- [ ] **Action 8.1.1.3**: Remove duplicate upload buttons
- **Scope**: All locations except primary - Remove duplicate buttons
- **Dependencies**: Action 8.1.1.2 complete
- **Risk**: MEDIUM (removes functionality)
- **Validation**: One upload button, consistent behavior
- **Rollback**: Restore duplicates
- [ ] **Action 8.1.1.4**: Ensure consistent upload behavior
- **Scope**: Primary upload button - Verify same behavior (opens modal/navigates)
- **Dependencies**: Action 8.1.1.3 complete
- **Risk**: LOW
- **Validation**: Upload button behavior consistent
- **Rollback**: N/A (verification)
### Sub-Epic 8.2: Visual Affordances 🟢
#### Task 8.2.1: Add Hover States to Interactive Elements
- [ ] **Action 8.2.1.1**: Add hover to track cards
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:413-470` - Add `hover:` classes, `cursor-pointer`
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Cards show hover state, cursor changes
- **Rollback**: Remove hover classes
- [ ] **Action 8.2.1.2**: Audit all interactive elements
- **Scope**: Search for `onClick`, `onMouseEnter`, buttons, links - List all interactive elements
- **Dependencies**: Action 8.2.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Complete list of interactive elements
- **Rollback**: N/A (audit)
- [ ] **Action 8.2.1.3**: Add hover to all clickable elements
- **Scope**: All elements from Action 8.2.1.2 - Add hover states and cursor-pointer
- **Dependencies**: Action 8.2.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: All clickable elements have hover
- **Rollback**: Remove hover classes
- [ ] **Action 8.2.1.4**: Add focus states for keyboard navigation
- **Scope**: All interactive elements - Add focus-visible states
- **Dependencies**: Action 8.2.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: All elements have focus states
- **Rollback**: Remove focus states
### Sub-Epic 8.3: Loading States 🟢
#### Task 8.3.1: Add Loading States to All Mutations
- [ ] **Action 8.3.1.1**: Add loading state to addToPlaylist button
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:137-145` - Use `isLoading` from mutation
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Button shows spinner when loading
- **Rollback**: Remove loading state
- [ ] **Action 8.3.1.2**: Audit all mutation buttons
- **Scope**: Search for mutation calls (`mutateAsync`, `mutate`) - List all mutation buttons
- **Dependencies**: Action 8.3.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Complete list of mutation buttons
- **Rollback**: N/A (audit)
- [ ] **Action 8.3.1.3**: Add loading states to all mutation buttons
- **Scope**: All buttons from Action 8.3.1.2 - Add loading states
- **Dependencies**: Action 8.3.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: All mutations show loading
- **Rollback**: Remove loading states
- [ ] **Action 8.3.1.4**: Create Spinner component (if doesn't exist)
- **Scope**: `apps/web/src/components/ui/Spinner.tsx` (create) - Reusable spinner component
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Spinner component works
- **Rollback**: Delete component
- [ ] **Action 8.3.1.5**: Use Spinner in loading states
- **Scope**: All loading states - Use Spinner component
- **Dependencies**: Action 8.3.1.4 complete
- **Risk**: LOW 🔒
- **Validation**: All loading states use Spinner
- **Rollback**: Remove Spinner usage
### Sub-Epic 8.4: Mode Indicators 🟢
#### Task 8.4.1: Show Bulk Mode Banner
- [ ] **Action 8.4.1.1**: Create bulk mode banner component
- **Scope**: `apps/web/src/components/BulkModeBanner.tsx` (create)
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Banner shows when bulk mode active
- **Rollback**: Delete component
- [ ] **Action 8.4.1.2**: Show banner in LibraryPage when bulk mode active
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx` - Add banner, show count
- **Dependencies**: Action 8.4.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Banner visible, shows "3 items selected"
- **Rollback**: Remove banner
- [ ] **Action 8.4.1.3**: Highlight selected items clearly
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:416-419` - Enhance selection styling
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Selected items clearly highlighted
- **Rollback**: Restore original styling
---
## EPIC 9: CONSISTENCY 🟢
**Priority**: UX/UI THIRD
**Goal**: Establish design system, enforce usage, reduce drift
### Sub-Epic 9.1: Color System 🟢
#### Task 9.1.1: Document Color Usage
- [ ] **Action 9.1.1.1**: Create color usage guide
- **Scope**: `apps/web/src/styles/COLOR_USAGE.md` (create)
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Guide documents when to use each color
- **Rollback**: Delete file
- [ ] **Action 9.1.1.2**: Audit Tailwind default color usage
- **Scope**: Search for `text-cyan-`, `bg-cyan-`, `border-cyan-` etc. - List all Tailwind default colors
- **Dependencies**: Action 9.1.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Complete list of Tailwind default colors
- **Rollback**: N/A (audit)
- [ ] **Action 9.1.1.3**: Remove Tailwind default colors
- **Scope**: All components from Action 9.1.1.2 - Replace with design system colors
- **Dependencies**: Action 9.1.1.2 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: No Tailwind default colors used
- **Rollback**: Restore Tailwind colors
- [ ] **Action 9.1.1.4**: Add ESLint rule to prevent Tailwind defaults
- **Scope**: `.eslintrc.js` - Add rule to warn on Tailwind default colors
- **Dependencies**: Action 9.1.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: ESLint warns on Tailwind defaults
- **Rollback**: Remove rule
### Sub-Epic 9.2: Component Library 🟢
#### Task 9.2.1: Audit Custom Buttons
- [ ] **Action 9.2.1.1**: Find all custom button implementations
- **Scope**: Search for `<button className="custom-styles">`, document locations
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: List of all custom buttons
- **Rollback**: N/A (audit)
- [ ] **Action 9.2.1.2**: Replace with Button component
- **Scope**: All custom buttons - Replace with `<Button>` from `@/components/ui/button`
- **Dependencies**: Action 9.2.1.1 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: All buttons use Button component
- **Rollback**: Restore custom buttons
- [ ] **Action 9.2.1.3**: Create ESLint rule to enforce Button usage
- **Scope**: `.eslintrc.js` - Add rule to warn on custom buttons
- **Dependencies**: Action 9.2.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: ESLint warns on custom buttons
- **Rollback**: Remove rule
- [ ] **Action 9.2.1.4**: Create component usage guide
- **Scope**: `apps/web/src/components/COMPONENT_USAGE.md` (create) - Document when to use each component
- **Dependencies**: Action 9.2.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Guide documents component usage
- **Rollback**: Delete file
- [ ] **Action 9.2.1.5**: Audit other custom components (not just buttons)
- **Scope**: Search for custom implementations of Card, Input, Select - List all custom components
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: List of custom components
- **Rollback**: N/A (audit)
- [ ] **Action 9.2.1.6**: Replace custom components with design system components
- **Scope**: All custom components from Action 9.2.1.5 - Replace with design system
- **Dependencies**: Action 9.2.1.5 complete
- **Risk**: MEDIUM
- **Validation**: All components use design system
- **Rollback**: Restore custom components
### Sub-Epic 9.3: Simplify Button Variants ✅ QUICK WIN
#### Task 9.3.1: Reduce Button Variants
- [ ] **Action 9.3.1.1**: Audit button variant usage
- **Scope**: `apps/web/src/components/ui/button.tsx` - List all 9 variants, usage count
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Usage count for each variant
- **Rollback**: N/A (audit)
- [ ] **Action 9.3.1.2**: Keep only: default, outline, ghost
- **Scope**: `apps/web/src/components/ui/button.tsx:10-24` - Remove neon, glass, premium variants
- **Dependencies**: Action 9.3.1.1 complete
- **Risk**: HIGH (breaking change)
- **Validation**: Only 3 variants exist
- **Rollback**: Restore variants
- [ ] **Action 9.3.1.3**: Replace removed variants with default/outline/ghost
- **Scope**: All components using removed variants - Replace with closest match
- **Dependencies**: Action 9.3.1.2 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: No references to removed variants
- **Rollback**: Restore variant usage
- [ ] **Action 9.3.1.4**: Remove excessive glows from remaining variants
- **Scope**: `apps/web/src/components/ui/button.tsx` - Simplify shadow/glow effects
- **Dependencies**: Action 9.3.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: Buttons have minimal glow
- **Rollback**: Restore glows
- [ ] **Action 9.3.1.5**: Update button variant documentation
- **Scope**: `apps/web/src/components/ui/button.tsx` - Add JSDoc comments for each variant
- **Dependencies**: Action 9.3.1.4 complete
- **Risk**: LOW 🔒
- **Validation**: Variants documented
- **Rollback**: Remove documentation
- [ ] **Action 9.3.1.6**: Test all button variants visually
- **Scope**: Create test page or storybook - Visual test of all variants
- **Dependencies**: Action 9.3.1.4 complete
- **Risk**: LOW 🔒
- **Validation**: All variants render correctly
- **Rollback**: N/A (testing)
### Sub-Epic 9.4: Clean Card Component ✅ QUICK WIN
#### Task 9.4.1: Simplify Card Styling
- [ ] **Action 9.4.1.1**: Remove gradients from Card
- **Scope**: `apps/web/src/components/ui/card.tsx:11-17` - Remove gradient classes
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Cards have no gradients
- **Rollback**: Restore gradients
- [ ] **Action 9.4.1.2**: Simplify borders and shadows
- **Scope**: `apps/web/src/components/ui/card.tsx` - Use `border-white/5`, `shadow-lg`
- **Dependencies**: Action 9.4.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Cards have clean, simple styling
- **Rollback**: Restore complex styling
### Sub-Epic 9.5: Clean Input Component ✅ QUICK WIN
#### Task 9.5.1: Simplify Input Styling
- [ ] **Action 9.5.1.1**: Audit Input component styling
- **Scope**: `apps/web/src/components/ui/input.tsx` - Review current styling
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Current styling documented
- **Rollback**: N/A (audit)
- [ ] **Action 9.5.1.2**: Remove unnecessary decorations from Input
- **Scope**: `apps/web/src/components/ui/input.tsx` - Remove complex styling, keep clean border
- **Dependencies**: Action 9.5.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Input has minimal, clean styling
- **Rollback**: Restore original styling
- [ ] **Action 9.5.1.3**: Simplify Input styling classes
- **Scope**: `apps/web/src/components/ui/input.tsx:13` - Remove complex classes, keep essentials
- **Dependencies**: Action 9.5.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Input has minimal, clean styling
- **Rollback**: Restore original classes
- [ ] **Action 9.5.1.4**: Update Input focus state to cyan border (not glow)
- **Scope**: `apps/web/src/components/ui/input.tsx` - Change focus ring to border, remove glow
- **Dependencies**: Action 9.5.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: Focus shows cyan border, no glow effect
- **Rollback**: Restore glow effect
- [ ] **Action 9.5.1.5**: Remove unnecessary Input decorations
- **Scope**: `apps/web/src/components/ui/input.tsx` - Remove backdrop-blur, complex transitions
- **Dependencies**: Action 9.5.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: Input has minimal decorations
- **Rollback**: Restore decorations
- [ ] **Action 9.5.1.6**: Test Input component visually
- **Scope**: Create test page - Visual test of Input component
- **Dependencies**: Action 9.5.1.4 complete
- **Risk**: LOW 🔒
- **Validation**: Input renders correctly
- **Rollback**: N/A (testing)
---
## EPIC 10: COGNITIVE LOAD 🟢
**Priority**: UX/UI THIRD
**Goal**: Reduce information overload, simplify choices, progressive disclosure
### Sub-Epic 10.1: Reduce Information Overload 🟢
#### Task 10.1.1: Simplify Dashboard
- [ ] **Action 10.1.1.1**: Show only 2-3 key metrics, hide rest behind "View All"
- **Scope**: `apps/web/src/pages/DashboardPage.tsx:132-164` - Show 2-3 stats, add "View All" button
- **Dependencies**: None
- **Risk**: MEDIUM (removes information)
- **Validation**: Dashboard shows fewer stats, expandable
- **Rollback**: Restore all stats visible
- [ ] **Action 10.1.1.2**: Create Tabs component (if doesn't exist)
- **Scope**: `apps/web/src/components/ui/tabs.tsx` (create) - Reusable tabs component
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Tabs component works
- **Rollback**: Delete component
- [ ] **Action 10.1.1.3**: Use tabs or accordions for secondary info
- **Scope**: `apps/web/src/pages/DashboardPage.tsx` - Group secondary info in tabs
- **Dependencies**: Action 10.1.1.2 complete
- **Risk**: MEDIUM (layout change)
- **Validation**: Secondary info in tabs
- **Rollback**: Restore single view
- [ ] **Action 10.1.1.4**: Create Accordion component (if doesn't exist)
- **Scope**: `apps/web/src/components/ui/accordion.tsx` (create) - Reusable accordion component
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Accordion component works
- **Rollback**: Delete component
- [ ] **Action 10.1.1.5**: Use accordions for collapsible sections
- **Scope**: Dashboard and other pages - Use accordions for secondary info
- **Dependencies**: Action 10.1.1.4 complete
- **Risk**: MEDIUM (layout change)
- **Validation**: Secondary info in accordions
- **Rollback**: Restore single view
### Sub-Epic 10.2: Remove Unnecessary Features 🟢
#### Task 10.2.1: Audit View Mode Toggle
- [ ] **Action 10.2.1.1**: Check if list view is used
- **Scope**: Analytics or user testing - Determine usage
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Usage data collected
- **Rollback**: N/A (audit)
- [ ] **Action 10.2.1.2**: Remove list view if unused, or make less prominent
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:286-309` - Remove or hide toggle
- **Dependencies**: Action 10.2.1.1 complete
- **Risk**: MEDIUM (removes feature)
- **Validation**: List view removed or hidden
- **Rollback**: Restore toggle
### Sub-Epic 10.3: Simplify Filters 🟢
#### Task 10.3.1: Hide Advanced Filters
- [ ] **Action 10.3.1.1**: Create AdvancedFilters component
- **Scope**: `apps/web/src/components/AdvancedFilters.tsx` (create) - Collapsible advanced filters
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Component works
- **Rollback**: Delete component
- [ ] **Action 10.3.1.2**: Combine search with "Advanced" toggle
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx:317-383` - Hide genre/format/sort behind "Advanced"
- **Dependencies**: Action 10.3.1.1 complete
- **Risk**: MEDIUM (hides functionality)
- **Validation**: Basic search visible, advanced hidden
- **Rollback**: Restore all filters visible
- [ ] **Action 10.3.1.3**: Add "Clear filters" button
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx` - Add button to clear all filters
- **Dependencies**: Action 10.3.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Clear button works
- **Rollback**: Remove button
### Sub-Epic 10.4: Progressive Disclosure 🟢
#### Task 10.4.1: Add Tooltips
- [ ] **Action 10.4.1.1**: Install tooltip library or create component
- **Scope**: `apps/web/package.json` - Add tooltip dependency (if needed)
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Tooltip component available
- **Rollback**: Remove dependency
- [ ] **Action 10.4.1.2**: Add tooltips to advanced features
- **Scope**: Advanced UI elements - Add tooltips explaining usage
- **Dependencies**: Action 10.4.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Tooltips appear on hover
- **Rollback**: Remove tooltips
- [ ] **Action 10.4.1.3**: Create onboarding flow for new users (optional)
- **Scope**: `apps/web/src/components/Onboarding.tsx` (create) - Guide new users through features
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Onboarding flow works
- **Rollback**: Delete component
- [ ] **Action 10.4.1.4**: Add "first time" detection
- **Scope**: `apps/web/src/utils/firstTime.ts` (create) - Detect first-time users
- **Dependencies**: Action 10.4.1.3 complete
- **Risk**: LOW
- **Validation**: First-time detection works
- **Rollback**: Delete utility
---
## EPIC 11: AESTHETIC IMPROVEMENTS 🔵
**Priority**: AESTHETICS LAST
**Goal**: Increase contrast, establish rhythm, reduce visual noise
### Sub-Epic 11.1: Increase Contrast ✅ QUICK WIN
#### Task 11.1.1: Fix Text Colors
- [ ] **Action 11.1.1.1**: Change primary text to white
- **Scope**: `apps/web/src/index.css:65` - Change `--kodo-text-main` to white
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Primary text is white, WCAG AA compliant
- **Rollback**: Restore original color
- [ ] **Action 11.1.1.2**: Use dim text sparingly
- **Scope**: All components - Replace `text-kodo-secondary` with `text-white` where appropriate
- **Dependencies**: Action 11.1.1.1 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: Dim text used only for secondary info
- **Rollback**: Restore original colors
- [ ] **Action 11.1.1.3**: Test WCAG AA compliance
- **Scope**: Use contrast checker - Verify 4.5:1 ratio minimum
- **Dependencies**: Action 11.1.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: All text meets WCAG AA
- **Rollback**: N/A (testing)
- [ ] **Action 11.1.1.4**: Fix any WCAG AA violations
- **Scope**: All text elements failing WCAG AA - Adjust colors to meet 4.5:1 ratio
- **Dependencies**: Action 11.1.1.3 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: All text meets WCAG AA
- **Rollback**: Restore original colors
- [ ] **Action 11.1.1.5**: Add automated contrast testing
- **Scope**: Add contrast testing to CI/CD or use tool like axe-core
- **Dependencies**: Action 11.1.1.4 complete
- **Risk**: LOW 🔒
- **Validation**: Contrast tests run in CI
- **Rollback**: Remove from CI
### Sub-Epic 11.2: Establish Visual Rhythm 🟢
#### Task 11.2.1: Implement 8px Grid System
- [ ] **Action 11.2.1.1**: Document grid system
- **Scope**: `apps/web/src/styles/GRID_SYSTEM.md` (create)
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Grid system documented
- **Rollback**: Delete file
- [ ] **Action 11.2.1.2**: Verify spacing scale aligns to 8px grid
- **Scope**: `apps/web/src/styles/design-tokens.css` - Ensure spacing values are multiples of 8px
- **Dependencies**: Action 7.2.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: All spacing values are multiples of 8px
- **Rollback**: Adjust spacing values
- [ ] **Action 11.2.1.3**: Align all elements to 8px grid
- **Scope**: All components - Use spacing multiples of 8px
- **Dependencies**: Action 11.2.1.2 complete, Action 7.2.1.3 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: All spacing aligns to grid
- **Rollback**: Restore original spacing
- [ ] **Action 11.2.1.4**: Add visual grid overlay tool (dev only)
- **Scope**: `apps/web/src/utils/gridOverlay.ts` (create) - Dev tool to show 8px grid overlay
- **Dependencies**: Action 11.2.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: Grid overlay works in dev mode
- **Rollback**: Delete utility
### Sub-Epic 11.3: Color Hierarchy 🟢
#### Task 11.3.1: Reduce Cyan Overuse
- [ ] **Action 11.3.1.1**: Audit cyan usage
- **Scope**: Search for `kodo-cyan` usage, count instances
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Usage count documented
- **Rollback**: N/A (audit)
- [ ] **Action 11.3.1.2**: Replace secondary cyan with steel
- **Scope**: Non-primary actions - Replace `kodo-cyan` with `kodo-steel`
- **Dependencies**: Action 11.3.1.1 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: Only primary actions use cyan
- **Rollback**: Restore cyan usage
- [ ] **Action 11.3.1.3**: Apply 80/20 rule (80% neutral, 20% color)
- **Scope**: All pages - Ensure color used sparingly
- **Dependencies**: Action 11.3.1.2 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: Pages follow 80/20 rule
- **Rollback**: Restore original colors
### Sub-Epic 11.4: Visual Restraint 🟢
#### Task 11.4.1: Remove Unnecessary Hover Effects
- [ ] **Action 11.4.1.1**: Audit hover effects
- **Scope**: All components - List all hover effects
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: List of hover effects
- **Rollback**: N/A (audit)
- [ ] **Action 11.4.1.2**: Categorize hover effects: necessary vs excessive
- **Scope**: All hover effects from Action 11.4.1.1 - Categorize each
- **Dependencies**: Action 11.4.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Hover effects categorized
- **Rollback**: N/A (categorization)
- [ ] **Action 11.4.1.3**: Remove excessive hover effects
- **Scope**: Non-interactive elements and excessive effects - Remove hover effects
- **Dependencies**: Action 11.4.1.2 complete
- **Risk**: LOW 🔒
- **Validation**: Only interactive elements have hover, effects are subtle
- **Rollback**: Restore hover effects
#### Task 11.4.2: Use Gradients Sparingly
- [ ] **Action 11.4.2.1**: Remove gradients from cards
- **Scope**: All Card components - Remove gradient backgrounds
- **Dependencies**: Action 9.4.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: No gradients on cards
- **Rollback**: Restore gradients
- [ ] **Action 11.4.2.2**: Keep gradients only for hero sections
- **Scope**: Hero/landing sections - Keep gradients if needed
- **Dependencies**: Action 11.4.2.1 complete
- **Risk**: LOW 🔒
- **Validation**: Gradients only in hero sections
- **Rollback**: Remove gradients
#### Task 11.4.3: Increase Whitespace
- [ ] **Action 11.4.3.1**: Add more padding to cards
- **Scope**: `apps/web/src/components/ui/card.tsx` - Increase padding
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Cards have more breathing room
- **Rollback**: Restore original padding
- [ ] **Action 11.4.3.2**: Audit section spacing
- **Scope**: All pages - List all section spacing values
- **Dependencies**: Action 7.2.1.3 complete
- **Risk**: LOW 🔒
- **Validation**: List of section spacing
- **Rollback**: N/A (audit)
- [ ] **Action 11.4.3.3**: Increase spacing between sections
- **Scope**: All pages from Action 11.4.3.2 - Increase spacing values
- **Dependencies**: Action 11.4.3.2 complete
- **Risk**: LOW 🔒
- **Validation**: Sections have more space
- **Rollback**: Restore original spacing
- [ ] **Action 11.4.3.4**: Add consistent section spacing utility
- **Scope**: `apps/web/src/styles/design-tokens.css` - Add `--section-spacing` variable
- **Dependencies**: Action 11.4.3.3 complete
- **Risk**: LOW 🔒
- **Validation**: Variable defined and used
- **Rollback**: Remove variable
### Sub-Epic 11.5: Define Style Direction 🟢
#### Task 11.5.1: Choose Design Direction
- [ ] **Action 11.5.1.1**: Document "Surgical Minimalism" direction
- **Scope**: `apps/web/src/styles/DESIGN_DIRECTION.md` (create)
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Direction documented with examples
- **Rollback**: Delete file
- [ ] **Action 11.5.1.2**: Create design direction checklist
- **Scope**: `apps/web/src/styles/DESIGN_DIRECTION.md` - Add checklist for applying direction
- **Dependencies**: Action 11.5.1.1 complete
- **Risk**: LOW 🔒
- **Validation**: Checklist created
- **Rollback**: Remove checklist
- [ ] **Action 11.5.1.3**: Apply direction to Dashboard
- **Scope**: `apps/web/src/pages/DashboardPage.tsx` - Apply design direction
- **Dependencies**: Action 11.5.1.2 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: Dashboard follows direction
- **Rollback**: Restore original styling
- [ ] **Action 11.5.1.4**: Apply direction to LibraryPage
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx` - Apply design direction
- **Dependencies**: Action 11.5.1.3 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: LibraryPage follows direction
- **Rollback**: Restore original styling
- [ ] **Action 11.5.1.5**: Apply direction to all pages
- **Scope**: All page components - Apply design direction
- **Dependencies**: Action 11.5.1.4 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: All pages follow direction
- **Rollback**: Restore original styling
- [ ] **Action 11.5.1.6**: Apply direction to all components
- **Scope**: All components - Follow design direction
- **Dependencies**: Action 11.5.1.5 complete
- **Risk**: MEDIUM (visual changes)
- **Validation**: All components follow direction
- **Rollback**: Restore original styling
---
## EXECUTION ORDER
### Phase 1: Stability & Correctness (Weeks 1-2)
1. Epic 1: API Contract Integrity (BLOCKER)
2. Epic 5: Security & Robustness (BLOCKER)
3. Epic 2: Data Flow Clarity (HIGH)
4. Epic 3: Error Propagation (HIGH)
5. Epic 4: State Ownership (HIGH)
### Phase 2: Quick Wins (Week 3)
1. Epic 7.1: Typography System ✅
2. Epic 7.2: Spacing System ✅
3. Epic 9.3: Simplify Button Variants ✅
4. Epic 9.4: Clean Card Component ✅
5. Epic 9.5: Clean Input Component ✅
6. Epic 11.1: Increase Contrast ✅
### Phase 3: UX Improvements (Weeks 4-5)
1. Epic 7: Visual Hierarchy
2. Epic 8: Interaction Clarity
3. Epic 9: Consistency
4. Epic 10: Cognitive Load
### Phase 4: Aesthetics & Polish (Week 6)
1. Epic 11: Aesthetic Improvements
### Phase 5: Scalability (Ongoing)
1. Epic 6: Scalability & Evolution
---
## VALIDATION CHECKLIST
After each epic:
- [ ] All tests pass
- [ ] No TypeScript errors
- [ ] No console errors
- [ ] Visual regression tests pass (if applicable)
- [ ] Performance metrics unchanged or improved
- [ ] Documentation updated
After each atomic action:
- [ ] Code compiles without errors
- [ ] No new console warnings
- [ ] Related functionality still works
- [ ] Git commit created (for rollback safety)
## TESTING REQUIREMENTS
### Epic 1: API Contract Integrity
- [ ] Unit tests for type generation script
- [ ] Integration tests for API client with generated types
- [ ] E2E tests for critical API endpoints
- [ ] Schema validation tests
### Epic 2: Data Flow Clarity
- [ ] Unit tests for debounce hook
- [ ] Integration tests for dashboard aggregation endpoint
- [ ] E2E tests for search/filter functionality
- [ ] Cache sync tests (multi-tab)
### Epic 3: Error Propagation
- [ ] Unit tests for ErrorDisplay component
- [ ] Unit tests for error categorization
- [ ] Integration tests for error boundaries
- [ ] E2E tests for error recovery flows
### Epic 4: State Ownership
- [ ] Unit tests for useUser hook
- [ ] Integration tests for React Query migration
- [ ] E2E tests for state sync across tabs
- [ ] Performance tests for state updates
### Epic 5: Security & Robustness
- [ ] Security audit for token storage changes
- [ ] Integration tests for cookie-based auth
- [ ] E2E tests for rate limit UI
- [ ] Penetration tests for XSS vulnerabilities
### Epic 6: Scalability & Evolution
- [ ] Bundle size tests
- [ ] Performance tests for virtualization
- [ ] Load tests for code splitting
- [ ] Memory leak tests
### Epic 7-11: UI/UX Improvements
- [ ] Visual regression tests
- [ ] Accessibility tests (WCAG AA)
- [ ] Cross-browser tests
- [ ] Mobile responsiveness tests
## DOCUMENTATION REQUIREMENTS
### Epic 1: API Contract Integrity
- [ ] OpenAPI spec documentation
- [ ] Type generation guide
- [ ] Migration guide for manual types
- [ ] API versioning policy
### Epic 2-6: Architecture Changes
- [ ] State management migration guide
- [ ] Error handling guide
- [ ] Security best practices
- [ ] Performance optimization guide
### Epic 7-11: UI/UX Improvements
- [ ] Design system documentation
- [ ] Component usage guide
- [ ] Color usage guide
- [ ] Typography guide
- [ ] Spacing guide
---
## ROLLBACK PROCEDURE
If any task fails:
1. Check git status: `git status`
2. Identify changed files
3. Revert: `git checkout -- <file>` or `git revert <commit>`
4. Run tests: `npm test`
5. Verify app works: `npm run dev`
6. Document issue in TODO list
7. Re-prioritize if needed
---
## CLEANUP TASKS
### Obsolete Files to Remove
- [ ] **Cleanup 1**: Remove LibraryPage.tsx.old if obsolete
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx.old`
- **Dependencies**: Action 2.2.1.3 complete
- **Risk**: LOW
- **Validation**: File deleted, no references
- **Rollback**: Restore from git
- [ ] **Cleanup 2**: Remove backup UI components if obsolete
- **Scope**: `apps/web/src/components/ui.backup/` (if exists)
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Backup directory deleted or empty
- **Rollback**: Restore from git
- [ ] **Cleanup 3**: Remove unused test files
- **Scope**: Audit test files - Remove obsolete/unused tests
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Only active tests remain
- **Rollback**: Restore from git
- [ ] **Cleanup 4**: Remove stores/auth.ts if obsolete
- **Scope**: `apps/web/src/stores/auth.ts` (if exists)
- **Dependencies**: Action 4.5.1.4 complete
- **Risk**: LOW
- **Validation**: File deleted, no imports
- **Rollback**: Restore from git
- [ ] **Cleanup 5**: Remove duplicate chat store
- **Scope**: Either `apps/web/src/stores/chat.ts` or `apps/web/src/features/chat/store/chatStore.ts` (whichever is obsolete)
- **Dependencies**: Action 4.5.1.5 complete
- **Risk**: MEDIUM
- **Validation**: Single chat store remains
- **Rollback**: Restore deleted store
- [ ] **Cleanup 6**: Remove obsolete state utility files
- **Scope**: Obsolete utilities from Action 4.6.1.2 - Delete unused files
- **Dependencies**: Action 4.6.1.3 complete
- **Risk**: LOW
- **Validation**: Obsolete utilities deleted
- **Rollback**: Restore from git
- [ ] **Cleanup 7**: Remove unused type files
- **Scope**: Obsolete type files from Action 1.1.3.11 - Delete if empty/redundant
- **Dependencies**: Action 1.1.3.11 complete
- **Risk**: LOW
- **Validation**: Unused type files deleted
- **Rollback**: Restore from git
### Code Cleanup
- [ ] **Cleanup 8**: Audit commented-out code
- **Scope**: Search for `//`, `/* */` - List all commented code blocks
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: List of commented code
- **Rollback**: N/A (audit)
- [ ] **Cleanup 9**: Remove commented-out code
- **Scope**: All commented code from Cleanup 8 - Remove if obsolete
- **Dependencies**: Cleanup 8 complete
- **Risk**: LOW
- **Validation**: No commented code blocks (or only necessary comments)
- **Rollback**: N/A (cleanup)
- [ ] **Cleanup 10**: Audit console.log statements
- **Scope**: Search for `console.log`, `console.error`, `console.warn` - List all
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: List of console statements
- **Rollback**: N/A (audit)
- [ ] **Cleanup 11**: Replace console.log with logger
- **Scope**: All console.log from Cleanup 10 - Replace with `logger.debug/info/error`
- **Dependencies**: Cleanup 10 complete
- **Risk**: LOW
- **Validation**: No console.log statements, all use logger
- **Rollback**: Restore console.log
- [ ] **Cleanup 12**: Remove console.error/warn (replace with logger)
- **Scope**: All console.error/warn from Cleanup 10 - Replace with logger
- **Dependencies**: Cleanup 11 complete
- **Risk**: LOW
- **Validation**: No console statements
- **Rollback**: Restore console statements
- [ ] **Cleanup 13**: Audit TODO comments
- **Scope**: Search for `TODO`, `FIXME`, `XXX` - List all TODO comments
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: List of TODO comments
- **Rollback**: N/A (audit)
- [ ] **Cleanup 14**: Address or remove TODO comments
- **Scope**: All TODOs from Cleanup 13 - Address or convert to GitHub issues
- **Dependencies**: Cleanup 13 complete
- **Risk**: LOW
- **Validation**: No TODO comments (or converted to issues)
- **Rollback**: N/A (cleanup)
- [ ] **Cleanup 15**: Remove unused imports
- **Scope**: All files - Remove unused imports (use ESLint rule)
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: No unused imports
- **Rollback**: N/A (cleanup)
- [ ] **Cleanup 16**: Remove unused variables
- **Scope**: All files - Remove unused variables (use ESLint rule)
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: No unused variables
- **Rollback**: N/A (cleanup)
- [ ] **Cleanup 17**: Remove dead code (unused functions/components)
- **Scope**: All files - Remove unused functions and components
- **Dependencies**: None
- **Risk**: MEDIUM (may break if referenced dynamically)
- **Validation**: No dead code
- **Rollback**: Restore deleted code
## EDGE CASES & FOLLOW-UPS
### Edge Case 1: Empty States
- [ ] **Edge 1.1**: Handle empty track list gracefully
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx` - Improve empty state UI
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Empty state shows helpful message
- **Rollback**: Restore original empty state
- [ ] **Edge 1.2**: Handle empty dashboard gracefully
- **Scope**: `apps/web/src/pages/DashboardPage.tsx` - Improve empty dashboard state
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Empty dashboard shows helpful message
- **Rollback**: Restore original empty state
- [ ] **Edge 1.3**: Handle empty search results
- **Scope**: `apps/web/src/features/library/pages/LibraryPage.tsx` - Improve empty search state
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Empty search shows helpful message
- **Rollback**: Restore original empty state
- [ ] **Edge 1.4**: Create reusable EmptyState component
- **Scope**: `apps/web/src/components/ui/EmptyState.tsx` (create) - Reusable empty state component
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Component works, reusable
- **Rollback**: Delete component
- [ ] **Edge 1.5**: Use EmptyState component everywhere
- **Scope**: All empty states - Use EmptyState component
- **Dependencies**: Edge 1.4 complete
- **Risk**: LOW 🔒
- **Validation**: All empty states use component
- **Rollback**: Remove component usage
### Edge Case 2: Network Failures
- [ ] **Edge 2.1**: Handle partial network failures
- **Scope**: `apps/web/src/services/api/client.ts` - Distinguish partial vs complete failure
- **Dependencies**: Action 3.5.1.1 complete
- **Risk**: MEDIUM
- **Validation**: Partial failures handled correctly
- **Rollback**: Remove partial failure handling
- [ ] **Edge 2.2**: Handle request cancellation
- **Scope**: `apps/web/src/services/api/client.ts` - Handle AbortController cancellation
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Cancelled requests handled gracefully
- **Rollback**: Remove cancellation handling
- [ ] **Edge 2.3**: Handle slow network connections
- **Scope**: `apps/web/src/services/api/client.ts` - Show loading indicators for slow requests
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Slow requests show loading
- **Rollback**: Remove loading indicators
### Edge Case 3: Concurrent Updates
- [ ] **Edge 3.1**: Handle concurrent state updates
- **Scope**: State management - Prevent race conditions in concurrent updates
- **Dependencies**: Epic 4 complete
- **Risk**: MEDIUM
- **Validation**: Concurrent updates don't conflict
- **Rollback**: Remove concurrency handling
- [ ] **Edge 3.2**: Handle rapid user interactions
- **Scope**: All interactive elements - Debounce/throttle rapid clicks
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Rapid interactions handled gracefully
- **Rollback**: Remove debounce/throttle
- [ ] **Edge 3.3**: Handle tab switching during operations
- **Scope**: Long-running operations - Handle tab visibility changes
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Operations continue correctly when tab switched
- **Rollback**: Remove visibility handling
### Edge Case 4: Large Datasets
- [ ] **Edge 4.1**: Test with large track lists (1000+ tracks)
- **Scope**: Performance testing - Verify virtualization handles large lists
- **Dependencies**: Action 6.3.1.2 complete
- **Risk**: LOW
- **Validation**: Large lists render smoothly
- **Rollback**: N/A (testing)
- [ ] **Edge 4.2**: Test with large playlists (100+ tracks)
- **Scope**: Performance testing - Verify playlist rendering
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Large playlists render smoothly
- **Rollback**: N/A (testing)
- [ ] **Edge 4.3**: Test with many conversations (100+)
- **Scope**: Performance testing - Verify chat list rendering
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Many conversations render smoothly
- **Rollback**: N/A (testing)
### Edge Case 5: Browser Compatibility
- [ ] **Edge 5.1**: Test BroadcastChannel support
- **Scope**: `apps/web/src/utils/broadcastSync.ts` - Verify fallback for unsupported browsers
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Fallback works in unsupported browsers
- **Rollback**: Remove fallback
- [ ] **Edge 5.2**: Test localStorage support
- **Scope**: All localStorage usage - Verify fallback for private browsing
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Fallback works in private browsing
- **Rollback**: Remove fallback
### Edge Case 6: Data Consistency
- [ ] **Edge 6.1**: Handle stale data in cache
- **Scope**: React Query cache - Ensure stale data refreshed appropriately
- **Dependencies**: Epic 4 complete
- **Risk**: MEDIUM
- **Validation**: Stale data refreshed correctly
- **Rollback**: Remove refresh logic
- [ ] **Edge 6.2**: Handle data conflicts (optimistic updates)
- **Scope**: Optimistic updates - Handle conflicts when server rejects
- **Dependencies**: Action 4.4.1.5 complete
- **Risk**: MEDIUM
- **Validation**: Conflicts handled gracefully
- **Rollback**: Remove conflict handling
## MONITORING & OBSERVABILITY
- [ ] **Monitor 1**: Set up error tracking for validation failures
- **Scope**: Monitoring setup - Track schema validation failures
- **Dependencies**: Action 1.2.2.1 complete
- **Risk**: LOW
- **Validation**: Errors tracked in monitoring
- **Rollback**: Remove tracking
- [ ] **Monitor 2**: Set up performance monitoring
- **Scope**: Monitoring setup - Track API response times, render times
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Performance metrics tracked
- **Rollback**: Remove monitoring
- [ ] **Monitor 3**: Set up user analytics (optional)
- **Scope**: Analytics setup - Track feature usage, errors
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Analytics working
- **Rollback**: Remove analytics
- [ ] **Monitor 4**: Set up performance monitoring
- **Scope**: Performance monitoring - Track render times, API response times
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Performance metrics tracked
- **Rollback**: Remove monitoring
- [ ] **Monitor 5**: Set up error tracking (Sentry or similar)
- **Scope**: Error tracking setup - Track runtime errors, unhandled exceptions
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: Errors tracked in monitoring
- **Rollback**: Remove error tracking
- [ ] **Monitor 6**: Set up API monitoring
- **Scope**: API monitoring - Track API response times, error rates
- **Dependencies**: None
- **Risk**: LOW
- **Validation**: API metrics tracked
- **Rollback**: Remove monitoring
- [ ] **Monitor 7**: Create monitoring dashboard
- **Scope**: Monitoring dashboard - Visualize metrics, errors, performance
- **Dependencies**: All monitoring setup complete
- **Risk**: LOW
- **Validation**: Dashboard shows metrics
- **Rollback**: Remove dashboard
---
## ADDITIONAL IMPLICIT TASKS
### Implicit Task 1: Update All File References
- [ ] **Implicit 1.1**: Update all imports after file moves/deletions
- **Scope**: All files - Update imports after cleanup tasks
- **Dependencies**: All cleanup tasks complete
- **Risk**: MEDIUM
- **Validation**: All imports valid, no broken references
- **Rollback**: Restore original imports
### Implicit Task 2: Update Documentation References
- [ ] **Implicit 2.1**: Update all documentation after changes
- **Scope**: All `.md` files - Update references to changed files/components
- **Dependencies**: All epics complete
- **Risk**: LOW 🔒
- **Validation**: Documentation accurate
- **Rollback**: Restore original documentation
### Implicit Task 3: Update Tests After Refactoring
- [ ] **Implicit 3.1**: Update unit tests after type changes
- **Scope**: All test files - Update tests for new types
- **Dependencies**: Epic 1 complete
- **Risk**: MEDIUM
- **Validation**: All tests pass
- **Rollback**: Restore original tests
- [ ] **Implicit 3.2**: Update integration tests after API changes
- **Scope**: All integration tests - Update for new API structure
- **Dependencies**: Epic 1, Epic 2 complete
- **Risk**: MEDIUM
- **Validation**: All tests pass
- **Rollback**: Restore original tests
- [ ] **Implicit 3.3**: Update E2E tests after UI changes
- **Scope**: All E2E tests - Update selectors for UI changes
- **Dependencies**: Epic 7-11 complete
- **Risk**: MEDIUM
- **Validation**: All tests pass
- **Rollback**: Restore original tests
### Implicit Task 4: Update TypeScript Config
- [ ] **Implicit 4.1**: Update tsconfig.json paths after file moves
- **Scope**: `apps/web/tsconfig.json` - Update path aliases if files moved
- **Dependencies**: All file moves complete
- **Risk**: LOW
- **Validation**: All paths valid
- **Rollback**: Restore original paths
### Implicit Task 5: Update Vite Config
- [ ] **Implicit 5.1**: Update vite.config.ts paths after file moves
- **Scope**: `apps/web/vite.config.ts` - Update path aliases if files moved
- **Dependencies**: All file moves complete
- **Risk**: LOW
- **Validation**: All paths valid
- **Rollback**: Restore original paths
### Implicit Task 6: Update ESLint Config
- [ ] **Implicit 6.1**: Update ESLint rules after component changes
- **Scope**: `.eslintrc.js` - Update rules for new component patterns
- **Dependencies**: Epic 9 complete
- **Risk**: LOW 🔒
- **Validation**: ESLint rules accurate
- **Rollback**: Restore original rules
### Implicit Task 7: Update Package.json Scripts
- [ ] **Implicit 7.1**: Add scripts for type generation
- **Scope**: `apps/web/package.json` - Add `generate:types` script
- **Dependencies**: Action 1.1.2.2 complete
- **Risk**: LOW 🔒
- **Validation**: Script works
- **Rollback**: Remove script
- [ ] **Implicit 7.2**: Add scripts for validation
- **Scope**: `apps/web/package.json` - Add validation scripts
- **Dependencies**: Epic 1 complete
- **Risk**: LOW 🔒
- **Validation**: Scripts work
- **Rollback**: Remove scripts
### Implicit Task 8: Update README
- [ ] **Implicit 8.1**: Update README with new setup steps
- **Scope**: `apps/web/README.md` - Update with type generation, new scripts
- **Dependencies**: All setup tasks complete
- **Risk**: LOW 🔒
- **Validation**: README accurate
- **Rollback**: Restore original README
### Implicit Task 9: Update Environment Variables
- [ ] **Implicit 9.1**: Document all environment variables
- **Scope**: `apps/web/.env.example` - Document all required variables
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: All variables documented
- **Rollback**: N/A (documentation)
- [ ] **Implicit 9.2**: Add validation for environment variables
- **Scope**: `apps/web/src/config/env.ts` - Validate required variables on startup
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Missing variables cause clear errors
- **Rollback**: Remove validation
### Implicit Task 10: Update Git Hooks
- [ ] **Implicit 10.1**: Add pre-commit hook for type checking
- **Scope**: `.husky/pre-commit` - Add type check before commit
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Type errors prevent commit
- **Rollback**: Remove hook
- [ ] **Implicit 10.2**: Add pre-commit hook for linting
- **Scope**: `.husky/pre-commit` - Add lint check before commit
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Lint errors prevent commit
- **Rollback**: Remove hook
- [ ] **Implicit 10.3**: Add pre-commit hook for tests (optional)
- **Scope**: `.husky/pre-commit` - Add test check before commit (optional, may be slow)
- **Dependencies**: None
- **Risk**: LOW 🔒
- **Validation**: Test failures prevent commit
- **Rollback**: Remove hook
---
## COMPLETE TASK BREAKDOWN
### By Epic:
- **Epic 1**: API Contract Integrity - 40+ actions
- **Epic 2**: Data Flow Clarity - 35+ actions
- **Epic 3**: Error Propagation - 30+ actions
- **Epic 4**: State Ownership - 50+ actions (includes store audits)
- **Epic 5**: Security & Robustness - 25+ actions
- **Epic 6**: Scalability & Evolution - 20+ actions
- **Epic 7**: Visual Hierarchy - 25+ actions
- **Epic 8**: Interaction Clarity - 20+ actions
- **Epic 9**: Consistency - 30+ actions
- **Epic 10**: Cognitive Load - 15+ actions
- **Epic 11**: Aesthetic Improvements - 25+ actions
- **Implicit Tasks**: 50+ actions
- **Edge Cases**: 25+ actions
- **Cleanup Tasks**: 20+ actions
- **Monitoring**: 10+ actions
- **Line-Specific Fixes**: 15+ actions
### By Category:
- **Type System**: 25+ actions (generation, migration, cleanup)
- **State Management**: 60+ actions (migration, cleanup, sync)
- **Error Handling**: 35+ actions (components, categories, recovery)
- **Security**: 20+ actions (tokens, validation, rate limits)
- **UI Components**: 40+ actions (cleanup, redesign, consistency)
- **Performance**: 15+ actions (virtualization, code splitting, caching)
- **Documentation**: 20+ actions (guides, updates, migration docs)
- **Testing**: 30+ actions (unit, integration, E2E, performance)
- **Cleanup**: 25+ actions (files, code, imports, dead code)
- **Monitoring**: 10+ actions (error tracking, performance, analytics)
### By Priority:
- **BLOCKERS**: 15+ actions (security, type generation)
- **HIGH**: 80+ actions (state management, error handling, data flow)
- **MEDIUM**: 200+ actions (UI improvements, consistency)
- **LOW**: 150+ actions (aesthetics, polish, cleanup)
### By Risk Level:
- **HIGH RISK**: 50+ actions (breaking changes, migrations)
- **MEDIUM RISK**: 150+ actions (refactoring, visual changes)
- **LOW RISK**: 250+ actions (safe improvements, audits)
### By Time Estimate:
- **Quick Wins (< 4 hours)**: 50+ actions
- **Medium Tasks (4-8 hours)**: 200+ actions
- **Large Tasks (8+ hours)**: 200+ actions
---
**Last Updated**: 2025-01-27
**Status**: Fully Enhanced - Ready for execution
**Total Actions**: 450+ atomic actions
**Next Review**: After Phase 1 completion
**Coverage**: 100% of analysis issues + implicit issues + edge cases + follow-ups + cleanup + monitoring + utilities + stores + components + line-specific fixes
## EXECUTION NOTES
### Before Starting:
1. Read entire TODO list
2. Understand dependencies
3. Set up monitoring
4. Create feature branch
5. Enable CI/CD checks
### During Execution:
1. Check off completed actions
2. Update dependencies if needed
3. Document any blockers
4. Run tests after each action
5. Commit frequently
### After Each Epic:
1. Run full test suite
2. Check for regressions
3. Update documentation
4. Review with team
5. Merge to main
### If Blocked:
1. Document blocker in TODO list
2. Mark task as `[!]` blocked
3. Move to next available task
4. Revisit blocker later
5. Update dependencies if needed + utilities + stores + components + edge cases
## FINAL ENHANCEMENTS SUMMARY
### Added Since Last Version:
1. **Complete Store Audit**: All Zustand stores (library, chat, ui, cart, player, auth)
2. **State Utility Cleanup**: undoRedo, stateMiddleware, stateNormalization, stateInvalidation, statePersistence, stateCleanup
3. **API Client Utilities**: requestDeduplication, responseCache, offlineQueue audit and UI
4. **Input Component**: Complete cleanup with all styling details
5. **Component Creation**: FAB, Sidebar, Collapsible, Tabs, Accordion, Spinner, EmptyState
6. **Edge Cases**: Empty states, network failures, concurrent updates, large datasets, browser compatibility, data consistency
7. **Implicit Tasks**: File imports, documentation, tests, configs, git hooks, breaking changes
8. **Granular Steps**: Broke down complex tasks into smaller atomic actions
9. **Audit Tasks**: Added audit steps before major changes
10. **Validation Tasks**: Added validation steps after changes
11. **Follow-up Tasks**: Added follow-up tasks for complex migrations
12. **Monitoring**: Added comprehensive monitoring setup
13. **Cleanup**: Added comprehensive cleanup tasks
14. **Documentation**: Added documentation requirements for all epics
15. **Testing**: Added testing requirements for all epics
### Coverage Details:
- ✅ Every file mentioned in analysis has corresponding tasks
- ✅ Every line number reference has specific action
- ✅ Every utility file has audit/update tasks
- ✅ Every store has migration/cleanup tasks
- ✅ Every component has cleanup/redesign tasks
- ✅ Every edge case has handling tasks
- ✅ Every implicit issue has explicit task
- ✅ Every follow-up has dedicated action
Reference in a new issue Copy permalink