# bashartomeza/masari architecture

> Architecture diagram of the GitHub repository bashartomeza/masari, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bashartomeza/masari
- Repository: https://github.com/bashartomeza/masari

## Overview

Masari is an Arabic-first corridor logistics product with an admin console and API; the README also identifies an Android client, though its source is not present in this tree. A typical operational flow is route setup and publication, passenger or merchant demand entry, matching and capacity handling, then trip operations and admin monitoring. The graph emphasizes the documented route-management and canonical-dispatch path; sampled excerpts do not establish every client-to-API or service-to-database call, so uncertain links are omitted.

Main entry points: [`apps/api/src/app.ts`](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/app.ts) (HTTP Application), [`apps/admin/src/App.tsx`](https://github.com/bashartomeza/masari/blob/production-readiness/apps/admin/src/App.tsx) (Admin App), [`apps/api/src/maps/previewService.ts`](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/maps/previewService.ts) (Preview Service), [`apps/api/src/lib/canonicalDispatchWorker.ts`](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/lib/canonicalDispatchWorker.ts) (Dispatch Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Admin Console"]
  node_admin_app["Admin App<br/>[App.tsx]"]
  node_route_ui["Route Workspace"]
  node_monitor_ui["Dispatch Monitoring"]
  node_overview_ui["Overview Dashboard"]
end

subgraph group_api["API Surface"]
  node_api_server["HTTP Application<br/>[app.ts]"]
end

subgraph group_routing["Route Management"]
  node_route_api["Route Endpoints<br/>[routeManagement.ts]"]
  node_preview_api["Route Preview<br/>[routePreview.ts]"]
  node_preview_service["Preview Service<br/>[previewService.ts]"]
  node_map_provider["Map Providers<br/>[liveProviders.ts]"]
  node_route_data["Route Snapshot"]
end

subgraph group_dispatch["Demand Dispatch"]
  node_passenger_api["Passenger Demand<br/>[canonicalDemand.ts]"]
  node_merchant_api["Merchant Demand<br/>[merchant.ts]"]
  node_matching_api["Canonical Matching"]
  node_shared_matching_api["Shared Matching"]
  node_dispatch_worker["Dispatch Worker"]
end

subgraph group_ops["Operations"]
  node_trip_api["Trip Operations<br/>[trips.ts]"]
  node_driver_api["Driver Operations<br/>[driver.ts]"]
  node_monitor_api["Match Monitoring"]
  node_monitor_service["Monitoring Service<br/>[service.ts]"]
  node_database[("MySQL Database")]
end

node_admin_user(("Admin"))
node_android_user(("Mobile User"))
node_maps_external["Map Services"]

node_admin_user -->|"uses"| node_admin_app
node_admin_app -->|"renders"| node_route_ui
node_admin_app -->|"renders"| node_overview_ui
node_admin_app -->|"renders"| node_monitor_ui
node_admin_app -->|"requests"| node_api_server
node_android_user -->|"submits demand"| node_api_server
node_api_server -->|"dispatches"| node_route_api
node_api_server -->|"dispatches"| node_preview_api
node_api_server -->|"dispatches"| node_passenger_api
node_api_server -->|"dispatches"| node_merchant_api
node_api_server -->|"dispatches"| node_matching_api
node_api_server -->|"dispatches"| node_shared_matching_api
node_api_server -->|"dispatches"| node_trip_api
node_api_server -->|"dispatches"| node_driver_api
node_api_server -->|"dispatches"| node_monitor_api
node_route_api -->|"reads/writes"| node_database
node_preview_api -->|"calls"| node_preview_service
node_preview_service -->|"reads"| node_database
node_preview_service -->|"requests routes"| node_map_provider
node_map_provider -.->|"queries"| node_maps_external
node_passenger_api -->|"snapshots route"| node_route_data
node_merchant_api -->|"snapshots route"| node_route_data
node_matching_api -->|"reads/writes"| node_database
node_shared_matching_api -->|"reads/writes"| node_database
node_dispatch_worker -->|"runs/expunges"| node_matching_api
node_dispatch_worker -->|"runs/expunges"| node_shared_matching_api
node_api_server -->|"starts"| node_dispatch_worker
node_trip_api -->|"reads/writes"| node_database
node_driver_api -->|"reads/writes"| node_database
node_monitor_api -->|"calls"| node_monitor_service
node_monitor_service -->|"reads"| node_database
node_monitor_ui -->|"requests monitoring"| node_api_server
node_overview_ui -->|"loads overview"| node_api_server
node_route_ui -->|"manages routes"| node_api_server

click node_admin_app "https://github.com/bashartomeza/masari/blob/production-readiness/apps/admin/src/App.tsx"
click node_route_ui "https://github.com/bashartomeza/masari/blob/production-readiness/apps/admin/src/features/routes/RouteManagement.tsx"
click node_monitor_ui "https://github.com/bashartomeza/masari/blob/production-readiness/apps/admin/src/features/monitoring/MatchingBatchingMonitoring.tsx"
click node_overview_ui "https://github.com/bashartomeza/masari/blob/production-readiness/apps/admin/src/features/overview/OverviewDashboard.tsx"
click node_api_server "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/app.ts"
click node_route_api "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/routeManagement.ts"
click node_preview_api "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/routePreview.ts"
click node_preview_service "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/maps/previewService.ts"
click node_map_provider "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/maps/liveProviders.ts"
click node_route_data "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/services/canonicalRouteSnapshots.ts"
click node_passenger_api "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/canonicalDemand.ts"
click node_merchant_api "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/merchant.ts"
click node_matching_api "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/canonicalMatching.ts"
click node_shared_matching_api "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/canonicalSharedMatching.ts"
click node_dispatch_worker "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/lib/canonicalDispatchWorker.ts"
click node_trip_api "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/trips.ts"
click node_driver_api "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/driver.ts"
click node_monitor_api "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/adminMatchingMonitoring.ts"
click node_monitor_service "https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/services/adminMatchingMonitoring/service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_admin_app,node_route_ui,node_monitor_ui,node_overview_ui,node_android_user toneBlue
class node_api_server toneAmber
class node_route_api,node_preview_api,node_preview_service,node_map_provider,node_route_data toneMint
class node_passenger_api,node_merchant_api,node_matching_api,node_shared_matching_api,node_dispatch_worker toneRose
class node_trip_api,node_driver_api,node_monitor_api,node_monitor_service,node_database,node_admin_user,node_maps_external toneIndigo
```

## Components

### Admin Console

- [Admin App](https://github.com/bashartomeza/masari/blob/production-readiness/apps/admin/src/App.tsx): `apps/admin/src/App.tsx`
- [Route Workspace](https://github.com/bashartomeza/masari/blob/production-readiness/apps/admin/src/features/routes/RouteManagement.tsx): `apps/admin/src/features/routes/RouteManagement.tsx`
- [Dispatch Monitoring](https://github.com/bashartomeza/masari/blob/production-readiness/apps/admin/src/features/monitoring/MatchingBatchingMonitoring.tsx): `apps/admin/src/features/monitoring/MatchingBatchingMonitoring.tsx`
- [Overview Dashboard](https://github.com/bashartomeza/masari/blob/production-readiness/apps/admin/src/features/overview/OverviewDashboard.tsx): `apps/admin/src/features/overview/OverviewDashboard.tsx`

### API Surface

- [HTTP Application](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/app.ts): `apps/api/src/app.ts`

### Route Management

- [Route Endpoints](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/routeManagement.ts): `apps/api/src/modules/routeManagement.ts`
- [Route Preview](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/routePreview.ts): `apps/api/src/modules/routePreview.ts`
- [Preview Service](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/maps/previewService.ts): `apps/api/src/maps/previewService.ts`
- [Map Providers](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/maps/liveProviders.ts): `apps/api/src/maps/liveProviders.ts`
- [Route Snapshot](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/services/canonicalRouteSnapshots.ts): `apps/api/src/services/canonicalRouteSnapshots.ts`

### Demand Dispatch

- [Passenger Demand](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/canonicalDemand.ts): `apps/api/src/modules/canonicalDemand.ts`
- [Merchant Demand](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/merchant.ts): `apps/api/src/modules/merchant.ts`
- [Canonical Matching](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/canonicalMatching.ts): `apps/api/src/modules/canonicalMatching.ts`
- [Shared Matching](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/canonicalSharedMatching.ts): `apps/api/src/modules/canonicalSharedMatching.ts`
- [Dispatch Worker](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/lib/canonicalDispatchWorker.ts): `apps/api/src/lib/canonicalDispatchWorker.ts`

### Operations

- [Trip Operations](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/trips.ts): `apps/api/src/modules/trips.ts`
- [Driver Operations](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/driver.ts): `apps/api/src/modules/driver.ts`
- [Match Monitoring](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/modules/adminMatchingMonitoring.ts): `apps/api/src/modules/adminMatchingMonitoring.ts`
- [Monitoring Service](https://github.com/bashartomeza/masari/blob/production-readiness/apps/api/src/services/adminMatchingMonitoring/service.ts): `apps/api/src/services/adminMatchingMonitoring/service.ts`
- **MySQL Database**

### Other components

- **Admin**
- **Mobile User**
- **Map Services**

## Connections

- Admin → Admin App: uses
- Admin App → Route Workspace: renders
- Admin App → Overview Dashboard: renders
- Admin App → Dispatch Monitoring: renders
- Admin App → HTTP Application: requests
- Mobile User → HTTP Application: submits demand
- HTTP Application → Route Endpoints: dispatches
- HTTP Application → Route Preview: dispatches
- HTTP Application → Passenger Demand: dispatches
- HTTP Application → Merchant Demand: dispatches
- HTTP Application → Canonical Matching: dispatches
- HTTP Application → Shared Matching: dispatches
- HTTP Application → Trip Operations: dispatches
- HTTP Application → Driver Operations: dispatches
- HTTP Application → Match Monitoring: dispatches
- Route Endpoints → MySQL Database: reads/writes
- Route Preview → Preview Service: calls
- Preview Service → MySQL Database: reads
- Preview Service → Map Providers: requests routes
- Map Providers → Map Services: queries
- Passenger Demand → Route Snapshot: snapshots route
- Merchant Demand → Route Snapshot: snapshots route
- Canonical Matching → MySQL Database: reads/writes
- Shared Matching → MySQL Database: reads/writes
- Dispatch Worker → Canonical Matching: runs/expunges
- Dispatch Worker → Shared Matching: runs/expunges
- HTTP Application → Dispatch Worker: starts
- Trip Operations → MySQL Database: reads/writes
- Driver Operations → MySQL Database: reads/writes
- Match Monitoring → Monitoring Service: calls
- Monitoring Service → MySQL Database: reads
- Dispatch Monitoring → HTTP Application: requests monitoring
- Overview Dashboard → HTTP Application: loads overview
- Route Workspace → HTTP Application: manages routes