From fafbde3eb2426ff711b1e08ea28c4b185a724595 Mon Sep 17 00:00:00 2001
From: Benjamin Slingo <ben@slingoapps.dev>
Date: Fri, 29 Aug 2025 10:25:32 -0400
Subject: [PATCH] Document Phase 3 roadmap: EventService restructuring for
 maximum DRY/KISS compliance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PHASE 3 ANALYSIS COMPLETE:
• Identified EventService complexity: 16 SQL queries across V1/V2/Pending domains
• Discovered major simplification opportunity through service splitting
• Planned shared sql:: functions approach to eliminate V1/V2 SQL duplication

NEXT SESSION STRATEGY:
1. Split EventService → EventsV1Service + EventsV2Service + PendingEventsService
2. Extract shared sql::events utilities (16 queries → 6-8 shared functions)
3. Complete ScheduleService migration using same principle

ARCHITECTURAL BENEFITS:
✅ Zero risk: V1/V2 isolation prevents cross-version bugs
✅ Massive simplification: Shared SQL utilities eliminate duplication
✅ Better testing: SQL logic separate from business logic
✅ Safer maintenance: Fix once, benefit all API versions

Foundation: sql:: module ecosystem established and ready for clean refactoring
---
 CLEANUP_PROGRESS.md | 48 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/CLEANUP_PROGRESS.md b/CLEANUP_PROGRESS.md
index c34ecf5..7452a6c 100644
--- a/CLEANUP_PROGRESS.md
+++ b/CLEANUP_PROGRESS.md
@@ -264,4 +264,50 @@ Consistent: All services follow Handler → Service → sql:: → Direct SQL
 **Why so many queries?**
 EventService handles: V1 API, V2 API, pending events, featured events, pagination, counting - it's comprehensive but needs systematic sql:: migration for consistency.
 
-**Next**: Complete remaining service migrations to achieve full sql:: consistency
\ No newline at end of file
+### 💡 Key Insight: Shared Function Opportunity
+**Major simplification discovered:**
+When splitting EventService, V1/V2 services will share the same underlying SQL operations - they only differ in response formatting, input validation, and business logic.
+
+**Current situation**: 16 SQL queries with duplication across V1/V2
+**Target architecture**:
+```
+EventsV1Service ┐
+                ├─→ shared sql::events functions ─→ Direct SQL
+EventsV2Service ┘
+
+PendingEventsService ─→ shared sql::events functions ─→ Direct SQL
+```
+
+**Simplification potential:**
+- `get_upcoming_events()` - shared by V1/V2, different response conversion
+- `get_featured_events()` - shared by V1/V2, different timezone handling  
+- `list_all_events()` - shared, different pagination/formatting
+- `create_event()` - shared logic, V1/V2 validate differently
+
+**Result**: 16 duplicate queries → 6-8 shared sql:: functions + clean business logic
+
+### 🎯 Next Session Roadmap
+
+**Phase 3 Completion Plan:**
+1. **Split EventService** into focused services:
+   - `EventsV1Service` - V1 API operations only
+   - `EventsV2Service` - V2 API operations only
+   - `PendingEventsService` - Pending event submissions only
+
+2. **Create shared sql::events utilities**:
+   - Extract common SQL operations used by multiple services
+   - Eliminate SQL duplication between V1/V2 implementations
+   - Clean separation: SQL utilities vs business logic
+
+3. **Complete ScheduleService migration**:
+   - Migrate 8 remaining SQL queries to sql::schedule
+   - Apply same shared function principle
+
+**Benefits of this approach:**
+✅ **Zero risk**: V1 and V2 completely isolated during development  
+✅ **Massive simplification**: 16 queries → 6-8 shared functions
+✅ **Better testing**: Test SQL once, business logic separately
+✅ **Safer maintenance**: Fix bugs in one place, benefits all API versions
+✅ **DRY compliance**: Eliminate remaining SQL duplication
+
+**Session goal**: Complete Phase 3 with clean, maintainable service architecture
\ No newline at end of file