feat: ride-hail

ride-hail/ABSTRACT.md

@@ -0,0 +1,17 @@
+# ride-hail 🚗
+
+## Learning Objectives
+
+- Advanced Message Queue Patterns
+- Real-Time Communication (WebSockets)
+- Geospatial Data Processing
+- Complex Microservices Orchestration
+- High-Concurrency Programming
+- Distributed State Management
+- Service-Oriented Architecture (SOA) Design Patterns
+
+## Abstract
+
+In this project, you will build a real-time distributed ride-hailing platform using Service-Oriented Architecture (SOA) principles. Using Go, you will create multiple microservices that communicate through RabbitMQ message queues and WebSocket connections to handle ride requests, driver matching, live location tracking, and ride coordination. This system simulates the complex backend infrastructure of modern transportation platforms like Uber, teaching you how to design systems that handle real-time data streams, coordinate moving entities, and maintain consistency across distributed components.
+
+This project represents the culmination of distributed systems knowledge: you'll implement sophisticated message routing patterns, handle geospatial calculations, manage real-time bidirectional communication, and orchestrate complex business workflows across multiple independent services following SOA best practices.

ride-hail/QUESTIONS.md

@@ -0,0 +1,199 @@
+## Project Setup and Compilation
+### Does the program compile successfully with `go build -o ride-hail-system .`?
+- [ ] Yes
+- [ ] No
+
+### Does the code follow gofumpt formatting standards?
+- [ ] Yes
+- [ ] No
+
+### Does the program handle runtime errors gracefully without crashing?
+- [ ] Yes
+- [ ] No
+
+### Is the program free of external packages except for pgx/v5, official AMQP client, and Gorilla WebSocket?
+- [ ] Yes
+- [ ] No
+
+## Database Architecture and Schema
+
+### Are all database tables created with proper constraints, foreign keys, and coordinate validations?
+- [ ] Yes
+- [ ] No
+
+### Does the ride_events table implement proper event sourcing for complete audit trail?
+- [ ] Yes
+- [ ] No
+
+### Are coordinate ranges properly validated (-90 to 90 lat, -180 to 180 lng) in the database layer?
+- [ ] Yes
+- [ ] No
+
+### Does the coordinates table support real-time location tracking with proper indexing?
+- [ ] Yes
+- [ ] No
+
+## Service-Oriented Architecture (SOA)
+
+### Are the three microservices (Ride, Driver & Location, Admin) properly separated with clear responsibilities?
+- [ ] Yes
+- [ ] No
+
+### Do services communicate through well-defined interfaces (APIs and message queues) following SOA principles?
+- [ ] Yes
+- [ ] No
+
+### Can each service be scaled and deployed independently?
+- [ ] Yes
+- [ ] No
+
+## RabbitMQ Message Architecture
+### Are RabbitMQ exchanges (ride_topic, driver_topic, location_fanout) configured correctly with proper routing keys?
+- [ ] Yes
+- [ ] No
+
+### Do services implement proper message acknowledgment patterns (basic.ack, basic.nack)?
+- [ ] Yes
+- [ ] No
+
+### Do all services handle RabbitMQ reconnection scenarios properly?
+- [ ] Yes
+- [ ] No
+
+### Does the location_fanout exchange properly broadcast location updates to all interested services?
+- [ ] Yes
+- [ ] No
+
+## Ride Service Implementation
+### Does the Ride Service accept HTTP POST requests on /rides endpoint and validate input according to specified rules?
+- [ ] Yes
+- [ ] No
+
+### Does the Ride Service generate unique ride numbers in format RIDE_YYYYMMDD_HHMMSS_XXX?
+- [ ] Yes
+- [ ] No
+
+### Does the Ride Service calculate fare estimates using dynamic pricing (base fare + distance/duration rates)?
+- [ ] Yes
+- [ ] No
+
+### Does the Ride Service store rides in database within a transaction and publish messages to RabbitMQ?
+- [ ] Yes
+- [ ] No
+
+### Does the system handle ride status transitions properly (REQUESTED → MATCHED → EN_ROUTE → ARRIVED → IN_PROGRESS → COMPLETED)?
+- [ ] Yes
+- [ ] No
+
+## Driver & Location Service
+### Does the Driver Service implement geospatial matching using PostGIS/Haversine formula within configurable radius?
+- [ ] Yes
+- [ ] No
+
+### Does the Driver Service score and rank drivers based on distance, rating, and completion rate?
+- [ ] Yes
+- [ ] No
+
+### Does the Driver Service send ride offers via WebSocket to top-ranked drivers with timeout mechanism?
+- [ ] Yes
+- [ ] No
+
+### Does the Driver Service handle driver acceptance/rejection and implement first-come-first-served matching?
+- [ ] Yes
+- [ ] No
+
+### Does the Location Service handle real-time location updates and calculate ETAs?
+- [ ] Yes
+- [ ] No
+
+### Does the Location Service broadcast processed location data via fanout exchange?
+- [ ] Yes
+- [ ] No
+
+### Does the driver matching algorithm complete within acceptable time limits?
+- [ ] Yes
+- [ ] No
+
+## WebSocket Real-Time Communication
+### Do all WebSocket connections implement proper authentication and handle ping/pong for connection health?
+- [ ] Yes
+- [ ] No
+
+### Are WebSocket connections authenticated within the 5-second timeout requirement?
+- [ ] Yes
+- [ ] No
+
+### Do WebSocket connections properly handle connection failures and reconnection scenarios?
+- [ ] Yes
+- [ ] No
+
+### Are location updates processed with minimal latency and sub-second response times?
+- [ ] Yes
+- [ ] No
+
+## Admin Service and Monitoring
+### Does the Admin Service provide system overview API with real-time metrics and active rides?
+- [ ] Yes
+- [ ] No
+
+### Do all services provide health check endpoints returning proper JSON format?
+- [ ] Yes
+- [ ] No
+
+## Logging and Observability
+### Do all services implement structured JSON logging with required fields (timestamp, level, service, action, message, hostname, request_id)?
+- [ ] Yes
+- [ ] No
+
+### Are correlation IDs properly used for distributed tracing across all services?
+- [ ] Yes
+- [ ] No
+
+## Configuration and Security
+### Can services be configured via YAML configuration file for database, RabbitMQ, and WebSocket settings?
+- [ ] Yes
+- [ ] No
+
+### Is JWT token authentication implemented for all API endpoints with role-based access controls?
+- [ ] Yes
+- [ ] No
+
+### Are input validations implemented for coordinates, addresses, and user data?
+- [ ] Yes
+- [ ] No
+
+## Performance and Reliability
+### Does the system handle concurrent ride requests efficiently without data corruption?
+- [ ] Yes
+- [ ] No
+
+### Do all database operations use transactions where appropriate and handle connection failures?
+- [ ] Yes
+- [ ] No
+
+### Do services implement graceful shutdown mechanisms?
+- [ ] Yes
+- [ ] No
+
+### Does the system maintain data consistency under high load conditions and concurrent operations?
+- [ ] Yes
+- [ ] No
+
+## Business Logic and Edge Cases
+### Are fare calculations implemented correctly with proper rates for different ride types (ECONOMY, PREMIUM, XL)?
+- [ ] Yes
+- [ ] No
+
+### Does the system handle edge cases (driver cancellations, invalid locations, duplicate requests)?
+- [ ] Yes
+- [ ] No
+
+### Does the system properly handle ride cancellations with appropriate status updates and notifications?
+- [ ] Yes
+- [ ] No
+
+## Detailed Feedback
+
+### What was great? What you liked the most about the program and the team performance?
+
+### What could be better? How those improvements could positively impact the outcome?