# ride-austin/server architecture

> Architecture diagram of the GitHub repository ride-austin/server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ride-austin/server
- Repository: https://github.com/ride-austin/server

## Overview

This project is a large, multi-module Maven server-side system implementing a ride-sharing backend as a set of JVM services and shared libraries. The root POM aggregates:

- Library modules (no ‘rest’ packages) providing shared domain objects, DSL repositories, utilities, event models, and generic services (common, common-rest, domain-base, domain, polygon, payments-domain, locations-domain, …).
- Service modules (contain ‘rest’, ‘jobs’, or ‘service’ packages) each exposing a narrowly scoped REST API or scheduled job via Spring/Jersey (app, admin-rest, active-drivers, avatar-management, documents, payments, promocodes, surge-pricing, notifications, reports, driver-statistics, user-tracking, etc.).
- An integration-test module (app-itests) that spins up MySQL and Redis via Docker for end-to-end test scenarios.
- A deploy module using Flyway for database migrations.

##### Main components
- Edge/API services:
- app (core rider/driver endpoints, authentication, ride-flow)
- admin-rest (admin dashboards, monitoring APIs)
- active-drivers, avatar-management, documents, payments, promocodes, surge-pricing, notifications, reports, driver-statistics, user-tracking, etc.
- Shared libraries: common, common-rest, domain-base, domain, payments-domain, locations-domain, events, cached-events, polygon, …
- Data stores:
- MySQL cluster (ride_db) – all services use JPA/DSL to persist domain data
- Redis cluster – session cache, location cache, surge areas, state-machine context
- Scheduler / batch jobs: either embedded (Quartz via scheduling module) or separate microservices (admin-jobs)
- Third-party integrations: Google Maps/Geocoding API, Twilio (SMS / phone lookup), Stripe / Payoneer (payments), Amazon SNS / S3, external config service, etc.

##### Relationships & data flows
- Clients (mobile/web) → HTTP/JSON → app or admin-rest
- app → shared libraries (common, domain) for business logic & persistence
- app / each microservice → MySQL / Redis
- app ↔ other services (e.g., ride-dispatch library, promotions, surge) via REST calls or shared message/events (Spring application events or pub-sub over Redis)
- scheduled jobs (Quartz or admin-jobs) trigger database cleanup, deactivation, report generation
- services → external HTTP → Google, Twilio, Stripe, Payoneer, AWS
- integration tests module spins up containers for MySQL/Redis and runs end-to-end scenarios

##### Architectural patterns
- Microservice decomposition by domain feature
- Layered architecture in each service: REST controllers → service layer → repository/DSL → domain models
- Shared library pattern for cross-cutting concerns (authentication, caching, utilities)
- Event-driven sub-system via Spring events / cached-events builder
- State machine for ride-dispatch in Redis
- Scheduled batch jobs via Quartz (scheduling module)

##### Significant technologies
- Java 8, Spring (Spring MVC / Jersey), JPA/Hibernate, Spring Data (DSL), Maven
- MySQL, Redis, Docker (app-itests), Flyway (deploy)
- Logback (logging), AOP for cross-cutting (app/aop), Freemarker templates (email & UI assets)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Clients["Mobile/Web Clients"]:::external

    %% API Gateway & Edge Services
    subgraph "API Gateway & Edge Services"
        direction TB
        app["app (API Gateway)"]:::microservice
        adminRest["admin-rest (Admin APIs)"]:::microservice
    end

    %% Microservices Cluster
    subgraph "Microservices Cluster"
        direction TB
        activeDrivers["active-drivers"]:::microservice
        avatarMgmt["avatar-management"]:::microservice
        documentsSvc["documents"]:::microservice
        paymentsSvc["payments"]:::microservice
        promocodesSvc["promocodes"]:::microservice
        surgePricing["surge-pricing"]:::microservice
        notificationsSvc["notifications"]:::microservice
        reportsSvc["reports"]:::microservice
        driverStats["driver-statistics"]:::microservice
        userTracking["user-tracking"]:::microservice
    end

    %% Scheduled Jobs
    subgraph "Scheduled / Batch Jobs"
        direction TB
        adminJobs["admin-jobs"]:::microservice
        schedulingMod["scheduling (Quartz Module)"]:::shared
    end

    %% Deployment & Testing
    subgraph "Deployment & Testing"
        direction TB
        deployMod["deploy (Flyway Migrations)"]:::shared
        itests["app-itests"]:::shared
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        commonLib["common"]:::shared
        commonRest["common-rest"]:::shared
        domainBase["domain-base"]:::shared
        domainLib["domain"]:::shared
        paymentsDomain["payments-domain"]:::shared
        locationsDomain["locations-domain"]:::shared
        polygonLib["polygon"]:::shared
        cacheLib["cache"]:::shared
        eventsLib["events"]:::shared
        cachedEvents["cached-events"]:::shared
        clientConfig["client-configuration"]:::shared
        currentUser["current-user-api"]:::shared
        thirdPartyDomain["thirdparty-domain"]:::shared
        thirdPartySdk["thirdparty"]:::shared
        webFilter["web-filter-domain"]:::shared
        testApi["test-api"]:::shared
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        mysql["MySQL Cluster"]:::datastore
        redis["Redis Cluster"]:::datastore
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        googleMaps["Google Maps API"]:::external
        twilio["Twilio SMS/Lookup"]:::external
        stripe["Stripe/Payoneer"]:::external
        aws["AWS (SNS/S3)"]:::external
    end

    %% Connections
    Clients -->|"HTTP/JSON"| app
    Clients -->|"HTTP/JSON"| adminRest

    app -->|uses| commonLib
    app -->|uses| commonRest
    app -->|uses| domainLib
    app -->|reads/writes| mysql
    app -->|cache| redis
    app -->|calls REST| activeDrivers
    app -->|calls REST| surgePricing
    app -->|calls REST| promocodesSvc
    app -->|calls REST| paymentsSvc
    app -->|calls REST| notificationsSvc

    adminRest -->|reads/writes| mysql
    adminRest -->|cache| redis

    activeDrivers -->|uses| domainLib
    activeDrivers -->|reads/writes| mysql

    %% Other microservices interactions
    surgePricing -->|reads/writes| redis
    documentsSvc -->|reads/writes| mysql
    paymentsSvc -->|external| stripe
    notificationsSvc -->|external| twilio
    reportsSvc -->|reads/writes| mysql
    driverStats -->|reads/writes| mysql
    userTracking -->|writes| redis

    %% Scheduled Jobs to DB
    adminJobs -->|runs jobs| mysql
    schedulingMod -->|triggers| adminJobs

    %% Deployment & Testing flows
    deployMod -->|migrates| mysql
    itests -->|spins up| mysql
    itests -->|spins up| redis
    itests -->|runs scenarios| app

    %% Shared Libs internal links
    commonRest --> commonLib
    domainLib --> domainBase
    cachedEvents --> eventsLib
    cacheLib --> redis

    %% External integrations
    app -->|geo| googleMaps
    app -->|sms| twilio
    paymentsSvc -->|payments| stripe
    documentsSvc -->|store| aws

    %% Click Events
    click app "https://github.com/ride-austin/server/tree/master/app/"
    click adminRest "https://github.com/ride-austin/server/tree/master/admin-rest/"
    click activeDrivers "https://github.com/ride-austin/server/tree/master/active-drivers/"
    click avatarMgmt "https://github.com/ride-austin/server/tree/master/avatar-management/"
    click documentsSvc "https://github.com/ride-austin/server/tree/master/documents/"
    click paymentsSvc "https://github.com/ride-austin/server/tree/master/payments/"
    click promocodesSvc "https://github.com/ride-austin/server/tree/master/promocodes/"
    click surgePricing "https://github.com/ride-austin/server/tree/master/surge-pricing/"
    click notificationsSvc "https://github.com/ride-austin/server/tree/master/notifications/"
    click reportsSvc "https://github.com/ride-austin/server/tree/master/reports/"
    click driverStats "https://github.com/ride-austin/server/tree/master/driver-statistics/"
    click userTracking "https://github.com/ride-austin/server/tree/master/user-tracking/"
    click adminJobs "https://github.com/ride-austin/server/tree/master/admin-jobs/"
    click schedulingMod "https://github.com/ride-austin/server/tree/master/scheduling/"
    click deployMod "https://github.com/ride-austin/server/tree/master/deploy/"
    click itests "https://github.com/ride-austin/server/tree/master/app-itests/"
    click commonLib "https://github.com/ride-austin/server/tree/master/common/"
    click commonRest "https://github.com/ride-austin/server/tree/master/common-rest/"
    click domainBase "https://github.com/ride-austin/server/tree/master/domain-base/"
    click domainLib "https://github.com/ride-austin/server/tree/master/domain/"
    click paymentsDomain "https://github.com/ride-austin/server/tree/master/payments-domain/"
    click locationsDomain "https://github.com/ride-austin/server/tree/master/locations-domain/"
    click polygonLib "https://github.com/ride-austin/server/tree/master/polygon/"
    click cacheLib "https://github.com/ride-austin/server/tree/master/cache/"
    click cachedEvents "https://github.com/ride-austin/server/tree/master/cached-events/"
    click eventsLib "https://github.com/ride-austin/server/tree/master/events/"
    click clientConfig "https://github.com/ride-austin/server/tree/master/client-configuration/"
    click currentUser "https://github.com/ride-austin/server/tree/master/current-user-api/"
    click thirdPartyDomain "https://github.com/ride-austin/server/tree/master/thirdparty-domain/"
    click thirdPartySdk "https://github.com/ride-austin/server/tree/master/thirdparty/"
    click webFilter "https://github.com/ride-austin/server/tree/master/web-filter-domain/"
    click testApi "https://github.com/ride-austin/server/tree/master/test-api/"

    %% Styles
    classDef microservice fill:#FFA500,stroke:#333,color:#000
    classDef shared fill:#add8e6,stroke:#333,color:#000
    classDef datastore fill:#90EE90,stroke:#333,color:#000
    classDef external fill:#D3D3D3,stroke:#333,color:#000
```
