RydeZee - Technical Design Document (TDD)

Version 1.0
Date: July 2026
Startup: RydeZee - Daily Commute Subscription Platform
Initial Launch: Hyderabad

Table of Contents

1. Introduction
2. Tech Stack
3. System Architecture
4. Database Schema
5. API Design
6. Key Modules & Features
7. Security & Compliance
8. Testing Strategy & Test Cases
9. Deployment & CI/CD
10. Monitoring & Observability
11. Scalability & Performance
12. Appendices

Introduction

This Technical Design Document outlines the complete technical blueprint for RydeZee. It ensures maintainable, scalable, and production-ready implementation aligned with the product requirements and investor-grade business plan.

Goals:

• High reliability for daily subscriptions
• Real-time tracking and notifications
• Gender/safety compliance
• Efficient matching for shared rides

Tech Stack

Frontend

• Framework: React 18 + Vite
• Styling: Tailwind CSS + shadcn/ui
• State Management: Zustand + TanStack Query
• Maps: MapmyIndia / Google Maps SDK
• Notifications: Firebase Cloud Messaging
• Forms: React Hook Form + Zod

Backend

• Runtime: Node.js 20 (Express.js) or FastAPI (Python) for performance-critical parts
• API: REST + WebSockets (Socket.io)
• Authentication: JWT + OAuth (Google, Phone)

Database

• Primary: PostgreSQL 16 + PostGIS (geospatial)
• Cache/Queue: Redis + BullMQ
• Search: Elasticsearch
• Vector (future): pgvector or Qdrant

Infrastructure

• Cloud: AWS / Vercel + Railway / Render (hybrid)
• Storage: Cloudflare R2
• CI/CD: GitHub Actions
• Container: Docker + Docker Compose

Other Tools

• Payments: Razorpay
• SMS/OTP: MSG91 or Twilio
• Logging: Winston + ELK
• Monitoring: Prometheus + Grafana + Sentry

System Architecture

High-level: Microservices-ready monolith initially.

• User Service
• Booking & Subscription Service
• Matching Engine
• Tracking & Notification Service
• Driver Service
• Payment Service
• Admin Dashboard

Real-time Layer: WebSockets for live tracking.

Database Schema

Key Tables (PostgreSQL):

• users (id, role: rider/driver/parent/admin, gender, preferences)
• subscriptions (id, user_id, route, vehicle_type, shared/premium, status)
• rides (id, subscription_id, date, driver_id, status)
• drivers (id, vehicle_details, verification_status, rating)
• locations (geospatial with PostGIS)

(Full schema with indexes, constraints detailed in appendices.)

API Design

Example Endpoints:

• POST /api/subscriptions/book
• GET /api/matching/nearby
• WebSocket: /ws/track/:rideId

(OpenAPI spec recommended.)

Key Modules & Features

Business Logic Layer

All core business rules are implemented in dedicated domain services (e.g., BookingService, MatchingService, SchoolService) following Domain-Driven Design principles. Rules are unit-tested, version-controlled, and auditable.

Subscription & Booking Business Logic

• A subscription guarantees a daily seat on the same route/driver for the subscribed period.
• Round-trip subscriptions auto-generate both legs with linked IDs.
• Price locked at booking time (no mid-subscription surges).

Matching Engine Core Rules

• Minimum route overlap: 70%
• Time window tolerance: ±15 minutes
• Max shared passengers: Vehicle capacity - 1 (driver)
• Dynamic fill after initial booking via notifications (valid for 48 hours)

Additional Truth Tables

Ride Type Decision Table

Backup Driver Trigger Truth Table

(Full set of decision tables in Appendices for implementation reference.)

1. Subscription Booking Logic

• Validate user preferences (gender, shared/premium).
• Calculate price based on distance, time, vehicle, sharing factor.
• Create subscription record with fixed daily seat guarantee.
• Handle round-trip vs single, pause/vacation modes.

2. Matching & Pooling Logic

• For shared rides: After initial booking, trigger radius-based notifications.
• Match on route overlap (>70% similarity), time window (±15 min), gender rules.
• Seat allocation: First-come, first-served with priority for same subscription route.

3. Gender Safety Logic (Truth Table)

Implementation: Enforced at matching engine level with database constraints and runtime checks.

4. School Mode Business Logic

• Only shared rides.
• Parent must verify guardian(s) via OTP/Aadhaar link.
• Pickup: Driver scans student QR or OTP → Notification to parent.
• Drop: Similar confirmation.
• Emergency: Geofence breach or SOS triggers immediate alerts + backup.

5. Driver Assignment & Backup Logic (Truth Table)

6. Notification & Real-time Logic

• Shared booking fill: Push + SMS to radius users.
• Daily reminders, delay alerts, arrival notifications.
• School: Pickup/Drop + location updates every 30s.

7. Cancellation & Refund Logic

• Before 24h: Full refund.
• Within 24h: Partial (50%) + seat released for re-pooling.
• No-show: Penalty points on rating.

(Additional business rules for pricing, renewals, corporate bulk, etc., are documented in appendices and enforced via domain services.)

Security & Compliance

• DPDP Act, Aggregator Guidelines
• Data encryption, rate limiting, audit logs

Testing Strategy & Test Cases

1. Unit Tests

• Backend: Jest / PyTest

  • Business Logic Test Cases:
    1. Subscription price calculation (distance, vehicle, shared discount, peak hours)
    2. Gender filtering (all combinations from truth table)
    3. Matching algorithm (route overlap, seat availability, fallback to premium)
    4. School pickup/drop OTP verification flow
    5. Backup driver allocation logic (all truth table conditions)
    6. Cancellation & refund rules (time-based, no-show penalties)
    7. Notification trigger conditions (radius, gender filter, fill rate)

• Frontend: Vitest + React Testing Library

  • Booking form validation with gender/preference rules
  • Real-time tracking UI updates
  • Subscription pause/vacation mode

2. Integration Tests

• Booking → Matching → Notification flow
• School tracking: Pickup/Drop OTP verification
• Driver acceptance workflow
• Database transactions for subscriptions

3. End-to-End (E2E) Tests

• Cypress / Playwright
  • Complete user journey: Register → Subscribe → Daily ride (shared + premium)
  • School parent flow: Guardian verification → Tracking + pickup/drop alerts + emergency
  • Failure scenarios: No seats available, backup driver trigger, gender mismatch rejection
  • Shared pooling: Initial booking → Radius notification → Seat fill → Confirmation

4. Performance & Load Tests

• k6 / JMeter: Simulate 1,000 concurrent bookings
• Geospatial query performance

5. Security Tests

• OWASP ZAP, penetration testing for auth bypass, data leaks

6. Manual & Exploratory

• Driver app usability
• Cross-device testing (Android/iOS Web)

Test Coverage Target: 85%+
CI Pipeline: Run on every PR

Deployment & CI/CD

• Staging → Production via GitHub Actions
• Blue-green deployments
• Feature flags (Unleash or LaunchDarkly)

Monitoring & Observability

• Error tracking: Sentry
• Metrics: On-time %, Fill rate, Churn
• Alerts for SLA breaches

Scalability & Performance

• Horizontal scaling
• Caching strategies
• Database sharding plan for pan-India

Appendices

• Full DB Schema (SQL)
• API Spec Examples
• Detailed Test Case Matrix (Excel-like table)
• Error Handling Strategy
• Future Migration to Microservices

This document serves as the single source of truth for development.
Use with CodeOrch MCP for implementation.

End of Document