# yoseph-m/semuni architecture

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

- Interactive diagram: https://gitdiagram.com/yoseph-m/semuni
- Repository: https://github.com/yoseph-m/semuni

## Overview

Semuni is a fare, wallet, payment, and settlement platform for Ethiopia’s minibus network. Its documented journey is passenger/driver authentication, fare and trip handling, passenger wallet payment, driver earnings, settlement visibility, and withdrawal requests. The graph emphasizes backend domain stages and the sampled driver-facing orchestration. Flutter application source is not present in the supplied tree, and several backend capability modules are unsampled; their paths are included where the tree confirms them, but uncertain call relationships are omitted.

Main entry points: [`backend/src/drivers/drivers.controller.ts`](https://github.com/yoseph-m/semuni/blob/main/backend/src/drivers/drivers.controller.ts) (Driver API), [`backend/src/auth/auth.service.ts`](https://github.com/yoseph-m/semuni/blob/main/backend/src/auth/auth.service.ts) (Authentication), [`backend/src/auth/auth.controller.ts`](https://github.com/yoseph-m/semuni/blob/main/backend/src/auth/auth.controller.ts) (Auth API), [`backend/src/wallets/wallets.service.ts`](https://github.com/yoseph-m/semuni/blob/main/backend/src/wallets/wallets.service.ts) (Wallet operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity &amp; access"]
  node_auth_api["Auth API<br/>[auth.controller.ts]"]
  node_auth_service["Authentication<br/>[auth.service.ts]"]
  node_user_profiles["User profiles<br/>[users.service.ts]"]
end

subgraph group_transport["Transport &amp; fares"]
  node_driver_api["Driver API"]
  node_driver_service["Driver profiles<br/>[drivers.service.ts]"]
  node_trips["Trips<br/>[trips.service.ts]"]
  node_routes["Routes<br/>[routes.service.ts]"]
  node_fares["Fare calculation<br/>[fares.service.ts]"]
  node_tariffs["Tariff management<br/>[tariffs.service.ts]"]
end

subgraph group_finance["Wallet &amp; finance"]
  node_wallet_api["Wallet API"]
  node_wallet_service["Wallet operations<br/>[wallets.service.ts]"]
  node_ledger["Ledger<br/>[ledger.service.ts]"]
  node_payments["Payments"]
  node_payment_providers["Payment providers"]
  node_settlements["Settlements"]
  node_withdrawals["Withdrawals"]
end

subgraph group_platform["Platform services"]
  node_notifications["Notifications"]
  node_maps["Maps<br/>[maps.service.ts]"]
  node_links_et["Receipt verification<br/>[links-et.client.ts]"]
end

node_passenger(("Passenger"))
node_driver(("Driver"))
node_admin(("Admin"))

node_passenger -->|"register / login"| node_auth_api
node_driver -->|"register / login"| node_auth_api
node_auth_api -.->|"handles auth"| node_auth_service
node_auth_service -->|"creates / looks up"| node_user_profiles
node_auth_service -->|"creates driver"| node_driver_service
node_driver -->|"views / requests"| node_driver_api
node_admin -->|"approves / suspends"| node_driver_api
node_driver_api -->|"reads / updates"| node_driver_service
node_driver_api -->|"reads earnings"| node_trips
node_driver_api -->|"lists routes"| node_routes
node_driver_api -->|"reads balance"| node_wallet_service
node_driver_api -->|"requests / lists"| node_withdrawals
node_driver_api -->|"looks up ride payer"| node_passenger
node_passenger -.->|"uses wallet"| node_wallet_api
node_wallet_api -->|"handles requests"| node_wallet_service
node_wallet_service -->|"records entries"| node_ledger
node_passenger -.->|"pays fare"| node_payments
node_payments -.->|"selects provider"| node_payment_providers
node_trips -->|"requests fare"| node_fares
node_driver -.->|"views settlements"| node_settlements
node_driver -->|"requests withdrawal"| node_withdrawals

click node_auth_api "https://github.com/yoseph-m/semuni/blob/main/backend/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/yoseph-m/semuni/blob/main/backend/src/auth/auth.service.ts"
click node_user_profiles "https://github.com/yoseph-m/semuni/blob/main/backend/src/users/users.service.ts"
click node_driver_api "https://github.com/yoseph-m/semuni/blob/main/backend/src/drivers/drivers.controller.ts"
click node_driver_service "https://github.com/yoseph-m/semuni/blob/main/backend/src/drivers/drivers.service.ts"
click node_trips "https://github.com/yoseph-m/semuni/blob/main/backend/src/trips/trips.service.ts"
click node_routes "https://github.com/yoseph-m/semuni/blob/main/backend/src/routes/routes.service.ts"
click node_fares "https://github.com/yoseph-m/semuni/blob/main/backend/src/fares/fares.service.ts"
click node_tariffs "https://github.com/yoseph-m/semuni/blob/main/backend/src/tariffs/tariffs.service.ts"
click node_wallet_api "https://github.com/yoseph-m/semuni/blob/main/backend/src/wallets/wallets.controller.ts"
click node_wallet_service "https://github.com/yoseph-m/semuni/blob/main/backend/src/wallets/wallets.service.ts"
click node_ledger "https://github.com/yoseph-m/semuni/blob/main/backend/src/ledger/ledger.service.ts"
click node_payments "https://github.com/yoseph-m/semuni/blob/main/backend/src/payments/payments.service.ts"
click node_payment_providers "https://github.com/yoseph-m/semuni/tree/main/backend/src/payments/providers"
click node_settlements "https://github.com/yoseph-m/semuni/blob/main/backend/src/settlements/settlements.service.ts"
click node_withdrawals "https://github.com/yoseph-m/semuni/blob/main/backend/src/withdrawals/withdrawals.service.ts"
click node_notifications "https://github.com/yoseph-m/semuni/tree/main/backend/src/notifications"
click node_maps "https://github.com/yoseph-m/semuni/blob/main/backend/src/maps/maps.service.ts"
click node_links_et "https://github.com/yoseph-m/semuni/blob/main/backend/src/links-et/links-et.client.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_auth_api,node_auth_service,node_user_profiles toneBlue
class node_driver_api,node_driver_service,node_trips,node_routes,node_fares,node_tariffs toneAmber
class node_wallet_api,node_wallet_service,node_ledger,node_payments,node_payment_providers,node_settlements,node_withdrawals toneMint
class node_notifications,node_maps,node_links_et toneRose
class node_passenger,node_driver,node_admin toneIndigo
```

## Components

### Identity & access

- [Auth API](https://github.com/yoseph-m/semuni/blob/main/backend/src/auth/auth.controller.ts): `backend/src/auth/auth.controller.ts`
- [Authentication](https://github.com/yoseph-m/semuni/blob/main/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [User profiles](https://github.com/yoseph-m/semuni/blob/main/backend/src/users/users.service.ts): `backend/src/users/users.service.ts`

### Transport & fares

- [Driver API](https://github.com/yoseph-m/semuni/blob/main/backend/src/drivers/drivers.controller.ts): `backend/src/drivers/drivers.controller.ts`
- [Driver profiles](https://github.com/yoseph-m/semuni/blob/main/backend/src/drivers/drivers.service.ts): `backend/src/drivers/drivers.service.ts`
- [Trips](https://github.com/yoseph-m/semuni/blob/main/backend/src/trips/trips.service.ts): `backend/src/trips/trips.service.ts`
- [Routes](https://github.com/yoseph-m/semuni/blob/main/backend/src/routes/routes.service.ts): `backend/src/routes/routes.service.ts`
- [Fare calculation](https://github.com/yoseph-m/semuni/blob/main/backend/src/fares/fares.service.ts): `backend/src/fares/fares.service.ts`
- [Tariff management](https://github.com/yoseph-m/semuni/blob/main/backend/src/tariffs/tariffs.service.ts): `backend/src/tariffs/tariffs.service.ts`

### Wallet & finance

- [Wallet API](https://github.com/yoseph-m/semuni/blob/main/backend/src/wallets/wallets.controller.ts): `backend/src/wallets/wallets.controller.ts`
- [Wallet operations](https://github.com/yoseph-m/semuni/blob/main/backend/src/wallets/wallets.service.ts): `backend/src/wallets/wallets.service.ts`
- [Ledger](https://github.com/yoseph-m/semuni/blob/main/backend/src/ledger/ledger.service.ts): `backend/src/ledger/ledger.service.ts`
- [Payments](https://github.com/yoseph-m/semuni/blob/main/backend/src/payments/payments.service.ts): `backend/src/payments/payments.service.ts`
- [Payment providers](https://github.com/yoseph-m/semuni/tree/main/backend/src/payments/providers): `backend/src/payments/providers`
- [Settlements](https://github.com/yoseph-m/semuni/blob/main/backend/src/settlements/settlements.service.ts): `backend/src/settlements/settlements.service.ts`
- [Withdrawals](https://github.com/yoseph-m/semuni/blob/main/backend/src/withdrawals/withdrawals.service.ts): `backend/src/withdrawals/withdrawals.service.ts`

### Platform services

- [Notifications](https://github.com/yoseph-m/semuni/tree/main/backend/src/notifications): `backend/src/notifications`
- [Maps](https://github.com/yoseph-m/semuni/blob/main/backend/src/maps/maps.service.ts): `backend/src/maps/maps.service.ts`
- [Receipt verification](https://github.com/yoseph-m/semuni/blob/main/backend/src/links-et/links-et.client.ts): `backend/src/links-et/links-et.client.ts`

### Other components

- **Passenger**
- **Driver**
- **Admin**

## Connections

- Passenger → Auth API: register / login
- Driver → Auth API: register / login
- Auth API → Authentication: handles auth
- Authentication → User profiles: creates / looks up (evidence: `backend/src/auth/auth.service.ts`)
- Authentication → Driver profiles: creates driver (evidence: `backend/src/auth/auth.service.ts`)
- Driver → Driver API: views / requests (evidence: `backend/src/drivers/drivers.controller.ts`)
- Admin → Driver API: approves / suspends (evidence: `backend/src/drivers/drivers.controller.ts`)
- Driver API → Driver profiles: reads / updates (evidence: `backend/src/drivers/drivers.controller.ts`)
- Driver API → Trips: reads earnings (evidence: `backend/src/drivers/drivers.controller.ts`)
- Driver API → Routes: lists routes (evidence: `backend/src/drivers/drivers.controller.ts`)
- Driver API → Wallet operations: reads balance (evidence: `backend/src/drivers/drivers.controller.ts`)
- Driver API → Withdrawals: requests / lists (evidence: `backend/src/drivers/drivers.controller.ts`)
- Driver API → Passenger: looks up ride payer (evidence: `backend/src/drivers/drivers.controller.ts`)
- Passenger → Wallet API: uses wallet
- Wallet API → Wallet operations: handles requests (evidence: `backend/src/wallets/wallets.controller.ts`)
- Wallet operations → Ledger: records entries (evidence: `backend/src/wallets/wallets.service.ts`)
- Passenger → Payments: pays fare (evidence: `README.md`)
- Payments → Payment providers: selects provider
- Trips → Fare calculation: requests fare (evidence: `backend/src/trips/trips.service.ts`)
- Driver → Settlements: views settlements (evidence: `README.md`)
- Driver → Withdrawals: requests withdrawal
