# mohamed2007sarhan/movexbackend architecture

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

- Interactive diagram: https://gitdiagram.com/mohamed2007sarhan/movexbackend
- Repository: https://github.com/mohamed2007sarhan/movexbackend
- Video tour (about a minute): https://gitdiagram.com/mohamed2007sarhan/movexbackend/video

## Overview

MoveX is a unified backend for on-demand services. Its main workflow is a user request entering the API, being handled by a vertical-specific service, becoming an order, progressing through fulfillment, and—where applicable—settling through the wallet. The README also documents bidding and AI matching, identity and role switching, safety/KYC, administration, tracking, promotions, and reviews. The excerpts show selected wiring; links for unsampled subsystems are included only where the README or sampled code supports them.

Main entry points: [`src/app.ts`](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/app.ts) (API application), [`src/db.ts`](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/db.ts) (PostgreSQL via Prisma), [`src/core/wallet/wallet.service.ts`](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/wallet/wallet.service.ts) (Wallet and ledger), [`src/modules/admin/admin.router.ts`](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/admin/admin.router.ts) (Admin suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_server["HTTP and socket server<br/>[server.ts]"]
  node_app["API application<br/>[app.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_gateway["Role gateway<br/>[gateway.router.ts]"]
end

subgraph group_verticals["Service verticals"]
  node_food["Food delivery<br/>[food.service.ts]"]
  node_ride["Ride-hailing<br/>[ride.service.ts]"]
  node_handyman["Handyman services"]
  node_moving["Moving logistics<br/>[moving.service.ts]"]
  node_bidding["Offers and bidding"]
end

subgraph group_core["Shared services"]
  node_ai["AI matching and mediation<br/>[ai.service.ts]"]
  node_orders["Order lifecycle engine"]
  node_database[("PostgreSQL via Prisma<br/>[db.ts]")]
  node_config["System configuration"]
  node_events["Event bus<br/>[event-bus.ts]"]
end

subgraph group_money["Wallet and finance"]
  node_wallet["Wallet and ledger<br/>[wallet.service.ts]"]
  node_topup["Wallet top-up"]
end

subgraph group_operations["Operations"]
  node_sockets["Socket service<br/>[socket.service.ts]"]
  node_safety["Safety and KYC<br/>[safety.router.ts]"]
  node_tracking["Delivery tracking<br/>[tracking.router.ts]"]
  node_eta["Delivery ETA"]
  node_admin["Admin suite<br/>[admin.router.ts]"]
  node_reviews["Reviews<br/>[reviews.router.ts]"]
  node_promotions["Promotions"]
end

node_user(("Customer / provider"))
node_admin_actor(("Administrator"))

node_user -->|"requests"| node_server
node_admin_actor -->|"administers"| node_server
node_server -->|"serves API"| node_app
node_server -->|"initializes"| node_sockets
node_app -->|"authenticates"| node_auth
node_app -->|"routes context"| node_gateway
node_app -->|"routes requests"| node_food
node_app -->|"routes requests"| node_ride
node_app -->|"routes requests"| node_handyman
node_app -->|"routes requests"| node_moving
node_app -->|"routes offers"| node_bidding
node_app -->|"routes AI requests"| node_ai
node_app -->|"initiates top-up"| node_topup
node_food -->|"creates orders"| node_orders
node_food -->|"reads and updates"| node_database
node_bidding -->|"requests mediation"| node_ai
node_bidding -->|"updates offers"| node_database
node_orders -->|"reads and writes"| node_database
node_orders -->|"settles completion"| node_wallet
node_wallet -->|"records ledger"| node_database
node_wallet -->|"reads limits"| node_config
node_wallet -->|"publishes events"| node_events
node_admin -->|"advances status"| node_orders
node_admin -->|"adjusts balances"| node_wallet
node_admin -->|"manages settings"| node_config
node_admin -->|"manages records"| node_database
node_eta -->|"reads parameters"| node_config
node_eta -->|"reads and updates"| node_database
node_safety -->|"records incidents"| node_database
node_safety -->|"dispatches alerts"| node_sockets
node_tracking -->|"reads tracking data"| node_database
node_reviews -->|"stores and reads"| node_database
node_promotions -->|"manages promotions"| node_database

click node_server "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/server.ts"
click node_app "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/app.ts"
click node_auth "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/auth/auth.service.ts"
click node_gateway "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/gateway/gateway.router.ts"
click node_food "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/food/food.service.ts"
click node_ride "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/ride/ride.service.ts"
click node_handyman "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/handyman/handyman.service.ts"
click node_moving "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/moving/moving.service.ts"
click node_bidding "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/bidding/offers.controller.ts"
click node_ai "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/ai/ai.service.ts"
click node_orders "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/order-engine/order-engine.service.ts"
click node_wallet "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/wallet/wallet.service.ts"
click node_topup "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/wallet/wallet-topup.service.ts"
click node_database "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/db.ts"
click node_config "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/config/system-config.service.ts"
click node_events "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/events/event-bus.ts"
click node_sockets "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/sockets/socket.service.ts"
click node_safety "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/safety/safety.router.ts"
click node_tracking "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/tracking/tracking.router.ts"
click node_eta "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/delivery/delivery-eta.service.ts"
click node_admin "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/admin/admin.router.ts"
click node_reviews "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/reviews/reviews.router.ts"
click node_promotions "https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/promotions/promotions.router.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_server,node_app,node_auth,node_gateway toneBlue
class node_food,node_ride,node_handyman,node_moving,node_bidding toneAmber
class node_ai,node_orders,node_database,node_config,node_events toneMint
class node_wallet,node_topup toneRose
class node_sockets,node_safety,node_tracking,node_eta,node_admin,node_reviews,node_promotions,node_user,node_admin_actor toneIndigo
```

## Components

### API and identity

- [HTTP and socket server](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/server.ts): `src/server.ts`
- [API application](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/app.ts): `src/app.ts`
- [Authentication](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/auth/auth.service.ts): `src/core/auth/auth.service.ts`
- [Role gateway](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/gateway/gateway.router.ts): `src/modules/gateway/gateway.router.ts`

### Service verticals

- [Food delivery](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/food/food.service.ts): `src/modules/food/food.service.ts`
- [Ride-hailing](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/ride/ride.service.ts): `src/modules/ride/ride.service.ts`
- [Handyman services](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/handyman/handyman.service.ts): `src/modules/handyman/handyman.service.ts`
- [Moving logistics](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/moving/moving.service.ts): `src/modules/moving/moving.service.ts`
- [Offers and bidding](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/bidding/offers.controller.ts): `src/bidding/offers.controller.ts`

### Shared services

- [AI matching and mediation](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/ai/ai.service.ts): `src/core/ai/ai.service.ts`
- [Order lifecycle engine](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/order-engine/order-engine.service.ts): `src/core/order-engine/order-engine.service.ts`
- [PostgreSQL via Prisma](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/db.ts): `src/db.ts`
- [System configuration](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/config/system-config.service.ts): `src/core/config/system-config.service.ts`
- [Event bus](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/events/event-bus.ts): `src/core/events/event-bus.ts`

### Wallet and finance

- [Wallet and ledger](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/wallet/wallet.service.ts): `src/core/wallet/wallet.service.ts`
- [Wallet top-up](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/wallet/wallet-topup.service.ts): `src/core/wallet/wallet-topup.service.ts`

### Operations

- [Socket service](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/sockets/socket.service.ts): `src/core/sockets/socket.service.ts`
- [Safety and KYC](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/safety/safety.router.ts): `src/modules/safety/safety.router.ts`
- [Delivery tracking](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/tracking/tracking.router.ts): `src/modules/tracking/tracking.router.ts`
- [Delivery ETA](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/core/delivery/delivery-eta.service.ts): `src/core/delivery/delivery-eta.service.ts`
- [Admin suite](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/admin/admin.router.ts): `src/modules/admin/admin.router.ts`
- [Reviews](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/reviews/reviews.router.ts): `src/modules/reviews/reviews.router.ts`
- [Promotions](https://github.com/mohamed2007sarhan/movexbackend/blob/main/src/modules/promotions/promotions.router.ts): `src/modules/promotions/promotions.router.ts`

### Other components

- **Customer / provider**
- **Administrator**

## Connections

- Customer / provider → HTTP and socket server: requests
- Administrator → HTTP and socket server: administers
- HTTP and socket server → API application: serves API
- HTTP and socket server → Socket service: initializes
- API application → Authentication: authenticates
- API application → Role gateway: routes context
- API application → Food delivery: routes requests
- API application → Ride-hailing: routes requests
- API application → Handyman services: routes requests
- API application → Moving logistics: routes requests
- API application → Offers and bidding: routes offers
- API application → AI matching and mediation: routes AI requests
- API application → Wallet top-up: initiates top-up
- Food delivery → Order lifecycle engine: creates orders
- Food delivery → PostgreSQL via Prisma: reads and updates
- Offers and bidding → AI matching and mediation: requests mediation
- Offers and bidding → PostgreSQL via Prisma: updates offers
- Order lifecycle engine → PostgreSQL via Prisma: reads and writes
- Order lifecycle engine → Wallet and ledger: settles completion
- Wallet and ledger → PostgreSQL via Prisma: records ledger
- Wallet and ledger → System configuration: reads limits
- Wallet and ledger → Event bus: publishes events
- Admin suite → Order lifecycle engine: advances status
- Admin suite → Wallet and ledger: adjusts balances
- Admin suite → System configuration: manages settings
- Admin suite → PostgreSQL via Prisma: manages records
- Delivery ETA → System configuration: reads parameters
- Delivery ETA → PostgreSQL via Prisma: reads and updates
- Safety and KYC → PostgreSQL via Prisma: records incidents
- Safety and KYC → Socket service: dispatches alerts
- Delivery tracking → PostgreSQL via Prisma: reads tracking data
- Reviews → PostgreSQL via Prisma: stores and reads
- Promotions → PostgreSQL via Prisma: manages promotions