feature/35 task api implement event zone search with venue management

.vscode/settings.json

@@ -1,9 +1,23 @@
 {
   "cSpell.words": [
+    "Asare",
+    "Calle",
+    "Chingu",
     "codepaths",
+    "Cristiano",
+    "Damilola",
     "datasource",
+    "datetime",
+    "geospatial",
+    "Honvedo",
+    "Hoxton",
+    "Morais",
+    "Oldrini",
+    "Oshinowo",
     "previewlanguage",
     "respawn",
-    "tsbuildinfo"
+    "tablao",
+    "tsbuildinfo",
+    "Valente"
   ]
 }

docs/2024.11.15_Approach_to_EventZoneSearch.md

@@ -0,0 +1,276 @@
+# Event Zone Search Feature Implementation Strategy
+
+## Overview
+Implementation of geospatial search functionality for live music events, including venue management and location-based queries.
+
+## Implementation Steps
+
+### Step 1: Add Venue Model & Basic CRUD ✅
+1. **Code Changes**
+   - Update Prisma schema with Venue model
+     - Basic fields: name, description, address
+     - JSON field for contact info (phone, email, website)
+     - String array for images
+     - Timestamps for auditing
+   - Create venue types/validation schemas using Zod
+   - Implement service with Prisma.InputJsonValue for JSON handling
+   - Follow existing controller/routes patterns for consistency
+
+2. **Testing**
+   - Add venue endpoints to Postman collection
+   - Create realistic example data
+   - Test validation rules
+   - Verify JSON field handling
+   - Check pagination and sorting
+
+3. **Documentation**
+   - Document API endpoints in Postman
+   - Include example requests/responses
+   - Document validation rules
+   - Add error scenarios
+
+4. **Learnings & Notes**
+   - JSON field requires special typing (Prisma.InputJsonValue)
+   - Keep consistent patterns with existing code
+   - Maintain proper TypeScript types throughout
+   - Consider validation rules carefully
+
+### Step 2: Enhance Venue with Geospatial ✅
+1. **Code Changes**
+   - Added coordinates as JSON field to Venue model
+   - Created CoordinatesSchema with validation:
+     - Latitude: -90 to 90
+     - Longitude: -180 to 180
+   - Added GeoJSON types and response formatting
+   - Implemented dedicated GeoJSON endpoint
+
+2. **Testing**
+   - Added geospatial queries to Postman
+   - Tested coordinate validation
+   - Verified GeoJSON format compliance
+   - Tested with real-world coordinates
+
+3. **Documentation**
+   - Added GeoJSON endpoint documentation
+   - Included coordinate validation rules
+   - Documented both response formats:
+     - Standard (lat/lng object)
+     - GeoJSON (coordinates array)
+
+4. **Learnings & Notes**
+   - GeoJSON uses [longitude, latitude] order (different from typical lat/lng)
+   - JSON fields in Prisma require InputJsonValue type for writes
+   - Coordinate validation is crucial for map reliability
+   - Separate endpoint for GeoJSON keeps responses clean
+
+### Step 3: Connect Events & Venues ✅
+1. **Code Changes**
+   - Updated Event model with venue relation
+     - Added venueId field
+     - Created foreign key constraint
+     - Removed redundant location field
+   - Enhanced Event responses with venue data
+     - Include venue details in responses
+     - Added GeoJSON endpoint for events
+     - Handle missing venue cases
+   - Updated validation schemas
+     - Added venueId validation
+     - Made venue required for events
+
+2. **Testing**
+   - Updated event endpoints in Postman
+   - Tested venue relationships
+   - Verified data integrity
+   - Tested GeoJSON responses
+   - Validated error cases
+
+3. **Documentation**
+   - Updated event endpoint docs
+   - Added GeoJSON format examples
+   - Documented relationship rules
+   - Added error scenarios
+
+4. **Learnings & Notes**
+   - Conditional chaining for optional venue data
+   - Type casting for JSON fields
+   - Consistent GeoJSON format between venues/events
+   - Error handling for missing venues
+
+5. **Technical Decisions**
+   - Include venue details in event responses
+   - Add dedicated GeoJSON endpoints
+   - Use consistent coordinate format
+   - Handle venue relationship errors
+
+6. **Key Learnings**
+   - Maintain data consistency
+   - Handle optional relationships
+   - Follow GeoJSON standards
+   - Consider error scenarios
+
+### Step 4: Implement Zone Search ✅
+1. **Code Changes**
+   - Added zone search endpoint to Event API
+   - Implemented Haversine formula for distance calculations
+   - Created GeoJSON FeatureCollection response
+   - Added filtering by date and status
+   - Included distance in event properties
+
+2. **Testing**
+   - Created realistic test data:
+     - 6 venues in New York (20km radius)
+     - 5 venues in Paris (15km radius)
+     - 4 venues in Berlin (10km radius)
+   - Added 2-3 events per venue
+   - Tested different search radiuses
+   - Verified distance calculations
+
+3. **Documentation**
+   - Created zone-search-testing.md guide
+   - Added example requests for each city
+   - Documented coordinate formats
+   - Included test scenarios
+
+4. **Technical Details**
+   - JavaScript-based distance calculation
+   - Sorted results by distance
+   - Rounded distances to 2 decimals
+   - Included search center in response
+
+5. **Key Learnings**
+   - Importance of realistic test data
+   - Need for proper coordinate validation
+   - Benefits of GeoJSON standard
+   - Performance considerations for distance calculations
+
+6. **Future Considerations**
+   - Potential PostGIS migration path
+   - Index optimization for larger datasets
+   - Additional spatial query features
+   - Performance monitoring needs
+
+## Final Deliverables
+
+### Pull Request
+- Title: "Feature: Event Zone Search Implementation"
+- Summary of all four steps
+- Reference to project requirements
+- Testing instructions
+- Migration steps
+
+### Documentation Updates
+- README.md updates
+- API documentation
+- Schema changes
+- New features description
+- Environment variables
+- Migration guide
+
+### Testing Package
+- Complete Postman collection
+- Example data
+- Test scenarios
+- Environment configurations
+
+## Notes
+- Maintain backward compatibility
+- Follow existing code patterns
+- Keep commits atomic
+- Update documentation inline
+- Test thoroughly at each step
+
+## Environment Considerations
+- PostgreSQL with PostGIS
+- GeoJSON support
+- Coordinate system standards
+- Distance calculation methods
+
+## Migration Notes
+- Database schema changes
+- New dependencies
+- Configuration updates
+- Backward compatibility
+
+## Best Practices (Updated from Step 1)
+1. **Code Organization**
+   - Keep types and validation together
+   - Use service layer for business logic
+   - Handle JSON fields properly
+   - Maintain consistent error handling
+
+2. **Testing Strategy**
+   - Test all CRUD operations
+   - Include validation edge cases
+   - Test pagination and sorting
+   - Verify JSON field handling
+
+3. **Documentation Approach**
+   - Document as you code
+   - Include real-world examples
+   - Show error scenarios
+   - Keep Postman in sync
+
+## Dependencies & Tools
+- Prisma with PostgreSQL
+- Zod for validation
+- Express.js
+- TypeScript
+- Postman for API testing
+
+## Migration Strategy
+1. Create new model
+2. Run migration
+3. Seed test data
+4. Verify existing functionality
+
+## Notes for Future Steps
+- Consider JSON field performance
+- Plan for data relationships
+- Think about validation complexity
+- Keep backward compatibility
+
+## Technical Decisions
+
+### Geospatial Implementation (Step 2)
+1. **Decision**: Implement geospatial features without PostGIS
+   - Store coordinates as JSON in PostgreSQL
+   - Implement distance calculations in JavaScript
+   - Return GeoJSON format responses
+
+2. **Rationale**:
+   - Render free tier doesn't support PostGIS extension
+   - Simple implementation sufficient for MVP needs
+   - Easier deployment and maintenance
+   - No additional database dependencies
+
+3. **Trade-offs**:
+   - ✅ Pros:
+     - Simpler deployment
+     - No additional dependencies
+     - Works with free tier hosting
+     - Easier to understand and maintain
+
+   - ❌ Cons:
+     - Less performant for large datasets
+     - Limited geospatial query capabilities
+     - Distance calculations less precise
+     - No spatial indexing
+
+4. **Future Considerations**:
+   - Can migrate to PostGIS later if needed
+   - Structure code to make future migration easier
+   - Monitor performance as data grows
+   - Consider upgrade path if advanced features needed
+
+5. **Implementation Details**:
+   - Coordinates stored as `{ lat: number, lng: number }`
+   - GeoJSON endpoint converts to `[longitude, latitude]`
+   - Strong validation prevents invalid coordinates
+   - TypeScript types ensure format consistency
+
+6. **Key Learnings**:
+   - Keep coordinate formats consistent
+   - Validate coordinates at schema level
+   - Consider map integration needs early
+   - Document coordinate order clearly
+   - Plan for future performance needs