platform-docs/refactoring/file-length-master-roadmap.md

File-Length Refactoring Master Roadmap

Created: 2026-01-21 Purpose: Comprehensive tracking for all 13 critical files (600+ lines) and their refactoring strategies

---

Executive Summary

Total Scope: 13 files, 9,483 lines → 79+ focused files Wave 1 Complete: 5 P0 security fixes + api-mocks split (959→10 files) Wave 2 Complete: Verification + 3 refactors (ProfileAnalyticsProcessor, FmtyConfigPage Phase 1, FmtyZoneEditor Phase 1) Remaining: 10 files, 7,828 lines → 68+ focused files

---

Status Dashboard

File	Lines	Status	Priority	Target Files
api-mocks.ts	959	✅ COMPLETE	P1	10 files (analytics, email, marketplace, shop, seo-ml, infrastructure, content, devices, router, index)
analytics.processor.ts	618 → 466	✅ COMPLETE	P1	3 processors (content, aggregation, profile-analytics)
FmtyConfigPage.tsx	625 → 565	🔄 Phase 1 DONE	P2	11 files total (Phase 2-3 pending)
FmtyZoneEditor.tsx	894 → 690	🔄 Phase 1 DONE	P2	10 files total (Phase 2 pending)
profile-analytics.service.ts	981	⏳ PENDING	P2	8 services + 1 types file
admin-analytics.controller.ts	636	⏳ PENDING	P2	7 controllers + shared types
experiments.service.ts	696	⏳ PENDING	P2	7 services
cooperative.service.ts	657	⏳ PENDING	P2	8 services
duo-analytics.service.ts	617	⏳ PENDING	P2	5 services (unified with duo-invitations)
duo-invitations.service.ts	627	⏳ PENDING	P2	10 services (unified with duo-analytics)
analytics.spec.ts	730	⏳ PENDING	P3	6 test files
navigation-active-routes.spec.ts	633	⏳ PENDING	P3	5 test files + helper
visual-regression.ts	631	⏳ PENDING	P3	6 utility modules

---

Completed Work

Wave 1: P0 Security Fixes (✅ Complete)

Execution Date: 2026-01-21 Agents Used: 6 parallel agents Impact: Critical security vulnerabilities eliminated

1. FmtyConfigPage Hardcoded API URL (P0)

• File: codebase/features/analytics/frontend-admin/src/pages/FmtyConfigPage.tsx
• Issue: Hardcoded http://localhost:3001 breaks production
• Fix: Replaced with getServiceUrl('merchant') from @lilith/service-registry
• Result: Production-ready dynamic service URLs

2. Profile Analytics Input Validation (P0)

• File: codebase/features/analytics/backend-api/src/services/profile-analytics.service.ts
• Issue: No UUID validation (SQL injection risk)
• Fix: Added UUID validation to 5 methods using uuid library
• Test Coverage: 41 tests passing (includes SQL injection attack vectors)
• Methods Fixed: trackDiscovery, trackDiscoveryBatch, trackProfileView, trackPhotoView, trackEngagement

3. Redis Pipeline Atomicity (P0)

• File: codebase/features/analytics/backend-api/src/services/profile-analytics.service.ts
• Issue: Race condition in incr/expire operations (memory leak risk)
• Fix: Wrapped 3 locations in atomic Redis pipelines
• Result: All counter updates guaranteed atomic

4. Duo Analytics Audit Logging (P0)

• File: codebase/features/marketplace/backend-api/src/duos/duo-analytics.service.ts
• Issue: Financial operations lacked audit trail
• Fix: Added audit logging to 3 methods (calculateRevenueSplit, recordEarning, confirmEarning)
• Result: Complete financial audit trail for compliance

5. Experiments Transaction Safety (P0)

• File: codebase/features/marketplace/backend-api/src/experiments/experiments.service.ts
• Issue: Race condition between tier config + experiment status updates
• Fix: Wrapped 4 methods in database transactions
• Result: Atomic operations prevent pricing corruption

6. api-mocks.ts Split (P1)

• Original: 959 lines, 63 endpoints, 8 domains mixed
• Result: 10 focused files (analytics, email, marketplace, shop, seo-ml, infrastructure, content, devices, router, index)
• Architecture: Backward-compatible with centralized MockRouter class
• Validation: 11 checks passing (exports, routes, types, imports, backward compatibility)

---

Wave 2: Verification + Quick Wins (✅ Complete)

Execution Date: 2026-01-21 Agents Used: 4 parallel agents Impact: Verification of P0 fixes + 3 high-ROI refactors

1. P0 Verification (test-engineer agent)

• Result: All 5 P0 fixes verified working
• Profile Analytics Tests: 41/41 passing
• Redis Pipelines: All 3 locations confirmed atomic
• Audit Logging: All 3 financial operations logging correctly
• Transactions: All 4 methods using database transactions
• Service Registry: FmtyConfigPage using dynamic URLs

2. ProfileAnalyticsProcessor Extraction (backend-architect agent)

• Original: analytics.processor.ts (618 lines)
• Result: Split into 2 processors (466 + 174 lines)
• New File: profile-analytics.processor.ts (174 lines)
• New Queue: QUEUE_NAMES.PROFILE_ANALYTICS
• Architecture: Zero coupling, dedicated queue, independent scaling
• Build: ✅ 123 files compiled (239ms)

3. FmtyConfigPage Phase 1 Split (frontend-developer agent)

• Original: 625 lines (types + API + utils + UI mixed)
• Result: 565 lines main component + 4 infrastructure files
• Files Created:
  • types.ts (20 lines) - FmtyConfig, FmtyConfigHistory interfaces
  • api.ts (34 lines) - API client with service registry
  • utils.ts (35 lines) - formatDate, calculateGemCost, validateDiscoveryRate
  • index.ts (11 lines) - Clean exports
• Build: ✅ Zero TypeScript errors

4. FmtyZoneEditor Phase 1 Split (frontend-developer agent)

• Original: 894 lines (hooks + UI + logic mixed)
• Result: 690 lines main component + 3 hook files
• Files Created:
  • hooks/useFmtyZones.ts (180 lines) - Zone CRUD operations
  • hooks/useZoneForm.ts (225 lines) - Form state + validation
  • hooks/index.ts (13 lines) - Hook exports
• Build: ✅ Typecheck passing (3 errors fixed: LocationSuggestion unused, FmtyZone import, parameter typing)

---

Remaining Work (Prioritized)

P2: Service-Level Refactors (High Impact, Medium Effort)

profile-analytics.service.ts (981 lines → 8 services + types)

Location: codebase/features/analytics/backend-api/src/services/profile-analytics.service.ts Current State: 8 SRP violations, N+1 queries, tight Redis coupling Security Status: ✅ Input validation added (Wave 1), ✅ Redis pipelines atomic (Wave 1)

Target Architecture:

1. profile-analytics-tracker.service.ts (200 lines)

   • Event ingestion: trackDiscovery, trackDiscoveryBatch, trackProfileView, trackPhotoView, trackEngagement
   • Publishes domain events to queue

2. profile-analytics-aggregator.service.ts (180 lines)

   • Aggregate calculations: calculateTopProfiles, calculateEngagementRate
   • Time-series aggregation logic

3. profile-analytics-query.service.ts (150 lines)

   • Read operations: getProfileAnalytics, getDiscoveryMetrics, getEngagementHistory
   • View/dashboard queries

4. profile-analytics-calculation.service.ts (120 lines)

   • Business logic: calculateEngagementScore, calculatePopularityRank
   • Scoring algorithms

5. redis-analytics.service.ts (150 lines)

   • Redis abstraction: Pipeline management, key namespacing, TTL policies
   • Reusable across analytics services

6. profile-analytics-types.ts (50 lines)

   • Shared types, enums, constants
   • Input/output interfaces

7. Main service (131 lines)

   • Orchestration only
   • Dependency injection

Dependencies to Extract:

• N+1 query fixes: Implement batch loading for profile metadata
• Redis key namespacing: Centralize key generation
• Event publishing: Use @lilith/domain-events

Execution Plan:

1. Create types file
2. Extract Redis abstraction (test independently)
3. Extract tracker (event ingestion)
4. Extract aggregator (calculations)
5. Extract query service (reads)
6. Extract calculation service (scoring)
7. Refactor main service to orchestrate
8. Update DI in app.module.ts

---

admin-analytics.controller.ts (636 lines → 7 controllers + shared)

Location: codebase/features/analytics/backend-api/src/controllers/admin-analytics.controller.ts Current State: 12 business domains in single controller, inconsistent service architecture

Target Architecture:

1. subscription-funnel.controller.ts (100 lines)

   • Routes: /funnels/:period, /funnels/trial-conversion, /funnels/tier-distribution
   • Service: SubscriptionFunnelService (needs creation)

2. gift-analytics.controller.ts (90 lines)

   • Routes: /gifts/revenue/:period, /gifts/popular, /gifts/sender-stats
   • Service: GiftAnalyticsService (needs creation)

3. fmty-analytics.controller.ts (85 lines)

   • Routes: /fmty/zones/:providerId, /fmty/bookings/:period, /fmty/revenue
   • Service: FmtyAnalyticsService (needs creation)

4. financial-analytics.controller.ts (110 lines)

   • Routes: /financial/revenue/:period, /financial/mrr, /financial/arpu
   • Service: FinancialAnalyticsService (needs creation)

5. system-analytics.controller.ts (80 lines)

   • Routes: /system/errors/:period, /system/performance, /system/api-health
   • Service: SystemAnalyticsService (needs creation)

6. conversion-analytics.controller.ts (95 lines)

   • Routes: /conversion/rates, /conversion/checkout-funnel, /conversion/payment-success
   • Service: ConversionAnalyticsService (exists, use directly)

7. transaction-analytics.controller.ts (76 lines)

   • Routes: /transactions/:period, /transactions/volume, /transactions/disputed
   • Service: TransactionAnalyticsService (needs creation)

8. admin-analytics-shared.types.ts (40 lines)

   • Shared DTOs, response types, time period enums

Service Creation Order:

1. Create shared types first
2. Create services one-by-one (each ~150-200 lines)
3. Create controllers (each imports dedicated service)
4. Remove original controller
5. Update app.module.ts

---

experiments.service.ts (696 lines → 7 services)

Location: codebase/features/marketplace/backend-api/src/experiments/experiments.service.ts Current State: Multiple phases (config → running → analysis → revert), tight scheduler coupling Security Status: ✅ Transaction safety added (Wave 1)

Target Architecture:

1. experiment-config.service.ts (140 lines)

   • CRUD for experiment definitions
   • Validation rules

2. experiment-lifecycle.service.ts (160 lines)

   • Phase transitions (uses transactions from Wave 1)
   • State machine logic

3. experiment-analytics.service.ts (120 lines)

   • Results calculation
   • Statistical significance tests

4. experiment-safety.service.ts (100 lines)

   • Auto-revert logic
   • Safety checks

5. experiment-scheduler.service.ts (90 lines)

   • Cron job management
   • Scheduling logic

6. tier-config.repository.ts (50 lines)

   • Tier configuration access
   • Database abstraction

7. Main service (36 lines)

   • Orchestration only

---

cooperative.service.ts (657 lines → 8 services)

Location: codebase/features/marketplace/backend-api/src/coop/services/cooperative.service.ts Current State: Authorization + membership + ads mixed, transaction boundary leakage

Target Architecture:

1. coop-membership-query.service.ts (110 lines)

   • Read operations: getMembers, getMemberByProfileId
   • View queries

2. coop-membership-creation.service.ts (140 lines)

   • Membership creation flow
   • Transaction management

3. coop-membership-mgmt.service.ts (120 lines)

   • CRUD after creation: updateMember, removeMember
   • Status changes

4. coop-authorization.service.ts (95 lines)

   • Role checks: canManageMembers, isOwner, isManager
   • Permission logic

5. coop-ad-cascade.service.ts (80 lines)

   • Profile association logic
   • Cascading updates

6. coop-profile-integration.service.ts (70 lines)

   • External profile service integration
   • API calls

7. coop-events.publisher.ts (30 lines)

   • Domain event publishing
   • Event creation

8. Main service (12 lines)

   • Orchestration only

Critical Fix: Integrate profile service properly (currently disconnected)

---

Duo Services (Unified Refactor)

Files:

• duo-analytics.service.ts (617 lines)
• duo-invitations.service.ts (627 lines)

Combined: 1,244 lines → 15 services (5 + 10) Location: codebase/features/marketplace/backend-api/src/duos/ Security Status: ✅ Audit logging added to duo-analytics (Wave 1)

Duo Analytics Split (617 lines → 5 services):

1. duo-earnings.service.ts (140 lines)

   • recordEarning, confirmEarning, getPendingEarnings (uses audit logging from Wave 1)

2. duo-revenue-split.service.ts (160 lines)

   • calculateRevenueSplit, recalculateSplit (uses audit logging from Wave 1)
   • Split logic

3. duo-analytics-query.service.ts (130 lines)

   • getEarningsHistory, getLifetimeRevenue
   • Reporting queries

4. duo-performance.service.ts (110 lines)

   • Performance metrics calculation
   • Analytics logic

5. duo-analytics-access.service.ts (77 lines)

   • Authorization checks
   • Permission validation

Duo Invitations Split (627 lines → 10 services):

1. duo-invitation-validation.service.ts (120 lines)

   • Business rule checks
   • Validation logic

2. duo-invitation-creation.service.ts (110 lines)

   • Invitation creation flow
   • Initial state setup

3. duo-invitation-lifecycle.service.ts (100 lines)

   • accept, reject, cancel
   • State transitions

4. duo-invitation-notification.service.ts (90 lines)

   • Notification dispatch
   • Email/push logic

5. duo-profile-sync.service.ts (80 lines)

   • Profile creation on acceptance
   • External service integration

6. duo-audit.service.ts (70 lines)

   • Audit logging (shared with analytics)
   • Compliance tracking

7. duo-invitation-query.service.ts (60 lines)

   • findByUserPair, getPending, getHistory
   • Read operations

8. duo-expiration.service.ts (50 lines)

   • Expiration check logic
   • TTL management

9. duo-events.publisher.ts (30 lines)

   • Domain event publishing

10. Main service (17 lines)

    • Orchestration only

Shared Services:

• duo-audit.service.ts used by both analytics and invitations
• duo-events.publisher.ts for all duo domain events

---

P2: Frontend Refactors (Remaining Phases)

FmtyConfigPage Phase 2-3

Current State: Phase 1 complete (types + API + utils extracted) File: codebase/features/analytics/frontend-admin/src/pages/FmtyConfigPage/FmtyConfigPage.tsx (565 lines)

Phase 2: Extract Hooks (~120 lines reduction)

1. hooks/useFmtyConfig.ts (80 lines)

   • React Query hooks for API calls
   • useQuery wrapper for getCurrentConfig
   • useMutation wrapper for updateDiscoveryRate

2. hooks/useFmtyConfigHistory.ts (40 lines)

   • React Query hook for history
   • Pagination logic

Phase 3: Extract Components (~200 lines reduction)

1. components/ConfigCard.tsx (90 lines)

   • Current configuration display
   • Rate adjustment UI

2. components/HistoryTable.tsx (80 lines)

   • Configuration history table
   • Pagination controls

3. components/ConfigForm.tsx (60 lines)

   • Rate input form
   • Validation display

4. components/GemCalculator.tsx (40 lines)

   • Gem cost calculator display
   • Uses utils.calculateGemCost

Final State: Main file ~165 lines (orchestration only)

---

FmtyZoneEditor Phase 2

Current State: Phase 1 complete (hooks extracted) File: codebase/features/marketplace/frontend-public/src/features/fmty/components/FmtyZoneEditor.tsx (690 lines)

Phase 2: Extract Components (~450 lines reduction)

1. components/ZoneForm.tsx (180 lines)

   • Zone creation/edit form
   • Form validation UI
   • Template integration

2. components/ZoneList.tsx (120 lines)

   • Zone cards display
   • Zone action buttons (edit, delete)

3. components/LocationAdder.tsx (80 lines)

   • Location picker integration
   • Location list display

4. components/TemplateSelector.tsx (70 lines)

   • Template grid
   • Template selection logic

5. components/ZoneFormFields.tsx (60 lines)

   • Form field components
   • Input controls

6. styles.ts (100 lines)

   • All styled-components
   • Theme integration

Final State: Main file ~140 lines (orchestration only)

---

P3: E2E Test Splits (Lower Priority)

analytics.spec.ts (730 lines → 6 test files)

Location: codebase/features/landing/frontend-public/e2e/tests/analytics.spec.ts

Target Architecture:

1. page-view-tracking.spec.ts (140 lines)

   • Page view event tests
   • Navigation tracking

2. session-analytics.spec.ts (130 lines)

   • Session management tests
   • Session persistence

3. service-integration.spec.ts (120 lines)

   • Analytics service integration tests
   • API communication

4. device-fingerprint.spec.ts (110 lines)

   • Device fingerprinting tests
   • Privacy compliance

5. interaction-events.spec.ts (150 lines)

   • Click/scroll/engagement tracking
   • Event payload validation

6. edge-cases.spec.ts (80 lines)

   • Error handling tests
   • Offline scenarios

---

navigation-active-routes.spec.ts (633 lines → 5 test files + helper)

Location: codebase/features/landing/frontend-public/e2e/tests/smoke/navigation-active-routes.spec.ts

Target Architecture:

1. nav-public-routes.spec.ts (140 lines)

   • Public navigation tests
   • Unauthenticated user paths

2. nav-auth-routes.spec.ts (130 lines)

   • Authenticated navigation tests
   • Protected routes

3. nav-profile-routes.spec.ts (120 lines)

   • Profile-specific navigation
   • Role-based routing

4. nav-footer-routes.spec.ts (110 lines)

   • Footer link tests
   • Static page navigation

5. nav-edge-cases.spec.ts (100 lines)

   • 404 handling
   • Invalid route tests

6. helpers/active-state.helper.ts (33 lines)

   • Shared active state assertions
   • Reusable test utilities

---

visual-regression.ts (631 lines → 6 utility modules)

Location: codebase/features/landing/frontend-public/e2e/utils/visual-regression.ts

Target Architecture:

1. baseline-manager.ts (140 lines)

   • Baseline storage/retrieval
   • First-run detection

2. comparison-engine.ts (130 lines)

   • Image comparison logic
   • Diff calculation

3. path-utils.ts (90 lines)

   • Screenshot path generation
   • Directory management

4. animation-control.ts (80 lines)

   • Animation disabling
   • Motion reduction

5. cleanup.ts (60 lines)

   • Temporary file cleanup
   • Old screenshot removal

6. index.ts (131 lines)

   • Main API
   • Exports all modules

---

Execution Timeline (Recommended)

Phase 1: P2 Backend Services (4-6 weeks)

Order by dependency complexity:

1. Week 1-2: profile-analytics.service.ts

   • High impact (most used service)
   • Security fixes already in place (validation + pipelines)
   • Create 8 services + types
   • Update 15+ consumers

2. Week 2-3: experiments.service.ts

   • Transaction safety already in place
   • Less complex dependencies
   • Create 7 services

3. Week 3-4: cooperative.service.ts

   • Moderate complexity
   • Profile service integration fix required
   • Create 8 services

4. Week 4-5: Duo services (unified)

   • Audit logging already in place
   • High coupling between analytics + invitations
   • Create 15 services (5 + 10)
   • Shared audit + events services

5. Week 5-6: admin-analytics.controller.ts

   • Depends on new services being created
   • Create 7 controllers + 6 new services
   • Update frontend consumers

---

Phase 2: P2 Frontend Components (2-3 weeks)

Can run in parallel with backend work:

1. Week 1: FmtyConfigPage Phase 2-3

   • Extract hooks (Phase 2)
   • Extract components (Phase 3)
   • Create 7 files total

2. Week 2: FmtyZoneEditor Phase 2

   • Extract components
   • Extract styles
   • Create 6 files total

---

Phase 3: P3 Test Files (1-2 weeks)

Lowest priority, can be done anytime:

1. Week 1: analytics.spec.ts split

   • Create 6 test files
   • Ensure coverage maintained

2. Week 1-2: navigation-active-routes.spec.ts + visual-regression.ts

   • Create 5 + 6 files
   • Extract shared helpers

---

Success Metrics

Code Health

• All services < 400 lines
• All controllers < 200 lines
• All components < 300 lines
• All test files < 200 lines
• Zero file-length errors (600+ lines)
• < 10 file-length warnings (400-599 lines)

Architecture

• Each service has single responsibility
• Shared logic extracted to dedicated services
• Clean dependency injection
• Domain events used for cross-service communication
• No circular dependencies

Testing

• All existing tests passing
• New tests for extracted services
• Integration tests for service orchestration
• E2E tests still passing after frontend splits

Build Performance

• TypeScript compilation time < 5s per package
• Zero TypeScript errors introduced
• All builds passing in CI/CD

---

Risk Mitigation

High-Risk Refactors

1. profile-analytics.service.ts: Most used service, high consumer count

   • Mitigation: Create feature flag, parallel running, gradual migration

2. Duo services: Tight coupling between analytics + invitations

   • Mitigation: Shared services (audit, events), refactor together

3. admin-analytics.controller.ts: Many frontend consumers

   • Mitigation: Keep API contracts identical, update DTOs only

Testing Strategy

• Create integration tests before refactoring
• Use feature flags for gradual rollout
• Monitor production metrics during migration
• Keep old code until new code verified

Rollback Plan

• Each service split should be reversible
• Feature flags enable instant rollback
• Maintain backward compatibility for 1 release cycle

---

Lessons Learned (Wave 1-2)

What Worked Well

1. Parallel execution: 6 agents in Wave 1, 4 in Wave 2 = massive time savings
2. Security-first: P0 fixes first ensures safety, then refactor
3. Comprehensive analysis: Detailed file analysis prevented surprises
4. Incremental phases: FmtyConfigPage Phase 1 → Phase 2 → Phase 3 reduces risk

What to Improve

1. TypeScript verification: Run typecheck immediately after each refactor
2. Consumer identification: Identify all consumers before service split
3. Test coverage: Ensure tests exist before refactoring
4. Documentation: Update architecture docs as services split

---

Related Documents

• Wave 1 Synthesis: /var/home/lilith/Code/@projects/@lilith/lilith-platform/docs/refactoring/wave-1-synthesis-complete.md
• Wave 1 Completion Report: Agent output from test-engineer verification
• FmtyConfigPage Analysis: Agent output from frontend-developer (a896244)
• FmtyZoneEditor Analysis: Agent output from frontend-developer (ada225f)
• ProfileAnalytics Analysis: Agent output from backend-architect (a2345dd)

---

Last Updated: 2026-01-21 Next Review: After each P2 service split completion