# smith-89/transit-link architecture

> Architecture diagram of the GitHub repository smith-89/transit-link, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smith-89/transit-link
- Repository: https://github.com/smith-89/transit-link

## Overview

Transit Link is a transit fare and operations MVP: riders maintain a wallet and use QR passes for station taps; validators record boarding and alighting, while operators review service activity and payouts. The backend exposes authentication, wallet, top-up, tap, and operator APIs; fare settlement, ledger, fraud, analytics, and payout logic form the domain layer. M-Pesa supports top-ups. The README was not supplied, and frontend call wiring is not excerpted, so browser-to-API links are marked unverified.

Main entry points: [`transit-link/app/main.py`](https://github.com/smith-89/transit-link/blob/main/transit-link/app/main.py) (App entry and routing), [`transit-link/app/routers/operator.py`](https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/operator.py) (Operator API), [`transit-link/app/trips.py`](https://github.com/smith-89/transit-link/blob/main/transit-link/app/trips.py) (Tap processing), [`transit-link/web/shared/api.js`](https://github.com/smith-89/transit-link/blob/main/transit-link/web/shared/api.js) (Shared API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User applications"]
  node_rider_app["Rider app<br/>[app.js]"]
  node_validator_app["Validator app<br/>[app.js]"]
  node_operator_app["Operator app<br/>[app.js]"]
  node_login_app["Login app<br/>[app.js]"]
  node_shared_api["Shared API client<br/>[api.js]"]
end

subgraph group_api["API and access"]
  node_entry["App entry and routing<br/>[main.py]"]
  node_auth["Authentication API<br/>[auth.py]"]
  node_wallet_api["Wallet API<br/>[wallet.py]"]
  node_topups_api["Top-up API<br/>[topups.py]"]
  node_taps_api["Tap API<br/>[taps.py]"]
  node_operator_api["Operator API<br/>[operator.py]"]
  node_security["Tokens and access<br/>[security.py]"]
end

subgraph group_fare["Fare and wallet"]
  node_trip_processing["Tap processing<br/>[trips.py]"]
  node_fare_rules["Fare rules<br/>[fares.py]"]
  node_ledger["Wallet ledger<br/>[ledger.py]"]
end

subgraph group_operations["Operator operations"]
  node_analytics["Service analytics<br/>[analytics.py]"]
  node_fraud["Fraud scanning<br/>[fraud.py]"]
  node_payouts["Operator payouts<br/>[payouts.py]"]
end

subgraph group_storage["Persistence and integration"]
  node_models["Domain records<br/>[models.py]"]
  node_db["Database sessions<br/>[db.py]"]
  node_database[("Transit data store<br/>[db.py]")]
  node_mpesa["M-Pesa client<br/>[mpesa.py]"]
  node_seed["Demo data setup<br/>[seed.py]"]
end

node_rider(("Rider"))
node_daraja["M-Pesa Daraja"]

node_rider -.->|"uses"| node_rider_app
node_rider_app -.->|"requests"| node_shared_api
node_validator_app -.->|"syncs taps"| node_shared_api
node_operator_app -.->|"requests"| node_shared_api
node_login_app -.->|"requests"| node_shared_api
node_shared_api -.->|"calls API"| node_entry
node_entry -->|"registers"| node_auth
node_entry -->|"registers"| node_wallet_api
node_entry -->|"registers"| node_topups_api
node_entry -->|"registers"| node_taps_api
node_entry -->|"registers"| node_operator_api
node_entry -->|"initializes"| node_db
node_entry -->|"seeds data"| node_seed
node_auth -->|"issues tokens"| node_security
node_auth -->|"reads and writes"| node_models
node_wallet_api -->|"reads balance"| node_ledger
node_topups_api -->|"starts payment"| node_mpesa
node_topups_api -->|"credits funds"| node_ledger
node_topups_api -->|"records top-up"| node_models
node_mpesa -.->|"requests payment"| node_daraja
node_taps_api -->|"processes taps"| node_trip_processing
node_trip_processing -->|"checks fares"| node_fare_rules
node_trip_processing -->|"debits and refunds"| node_ledger
node_trip_processing -->|"decodes pass"| node_security
node_operator_api -->|"summarizes service"| node_analytics
node_operator_api -->|"scans trips"| node_fraud
node_operator_api -->|"runs payout"| node_payouts
node_operator_api -->|"closes stale trips"| node_trip_processing
node_db -->|"connects"| node_database
node_db -->|"creates schema"| node_models
node_seed -->|"posts demo funds"| node_ledger
node_seed -->|"sets fares"| node_fare_rules

click node_rider_app "https://github.com/smith-89/transit-link/blob/main/transit-link/web/rider/app.js"
click node_validator_app "https://github.com/smith-89/transit-link/blob/main/transit-link/web/validator/app.js"
click node_operator_app "https://github.com/smith-89/transit-link/blob/main/transit-link/web/operator/app.js"
click node_login_app "https://github.com/smith-89/transit-link/blob/main/transit-link/web/login/app.js"
click node_shared_api "https://github.com/smith-89/transit-link/blob/main/transit-link/web/shared/api.js"
click node_entry "https://github.com/smith-89/transit-link/blob/main/transit-link/app/main.py"
click node_auth "https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/auth.py"
click node_wallet_api "https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/wallet.py"
click node_topups_api "https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/topups.py"
click node_taps_api "https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/taps.py"
click node_operator_api "https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/operator.py"
click node_security "https://github.com/smith-89/transit-link/blob/main/transit-link/app/security.py"
click node_trip_processing "https://github.com/smith-89/transit-link/blob/main/transit-link/app/trips.py"
click node_fare_rules "https://github.com/smith-89/transit-link/blob/main/transit-link/app/fares.py"
click node_ledger "https://github.com/smith-89/transit-link/blob/main/transit-link/app/ledger.py"
click node_analytics "https://github.com/smith-89/transit-link/blob/main/transit-link/app/analytics.py"
click node_fraud "https://github.com/smith-89/transit-link/blob/main/transit-link/app/fraud.py"
click node_payouts "https://github.com/smith-89/transit-link/blob/main/transit-link/app/payouts.py"
click node_models "https://github.com/smith-89/transit-link/blob/main/transit-link/app/models.py"
click node_db "https://github.com/smith-89/transit-link/blob/main/transit-link/app/db.py"
click node_database "https://github.com/smith-89/transit-link/blob/main/transit-link/app/db.py"
click node_mpesa "https://github.com/smith-89/transit-link/blob/main/transit-link/app/mpesa.py"
click node_seed "https://github.com/smith-89/transit-link/blob/main/transit-link/app/seed.py"

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_rider_app,node_validator_app,node_operator_app,node_login_app,node_shared_api toneBlue
class node_entry,node_auth,node_wallet_api,node_topups_api,node_taps_api,node_operator_api,node_security toneAmber
class node_trip_processing,node_fare_rules,node_ledger toneMint
class node_analytics,node_fraud,node_payouts toneRose
class node_models,node_db,node_database,node_mpesa,node_seed,node_rider,node_daraja toneIndigo
```

## Components

### User applications

- [Rider app](https://github.com/smith-89/transit-link/blob/main/transit-link/web/rider/app.js): `transit-link/web/rider/app.js`
- [Validator app](https://github.com/smith-89/transit-link/blob/main/transit-link/web/validator/app.js): `transit-link/web/validator/app.js`
- [Operator app](https://github.com/smith-89/transit-link/blob/main/transit-link/web/operator/app.js): `transit-link/web/operator/app.js`
- [Login app](https://github.com/smith-89/transit-link/blob/main/transit-link/web/login/app.js): `transit-link/web/login/app.js`
- [Shared API client](https://github.com/smith-89/transit-link/blob/main/transit-link/web/shared/api.js): `transit-link/web/shared/api.js`

### API and access

- [App entry and routing](https://github.com/smith-89/transit-link/blob/main/transit-link/app/main.py): `transit-link/app/main.py`
- [Authentication API](https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/auth.py): `transit-link/app/routers/auth.py`
- [Wallet API](https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/wallet.py): `transit-link/app/routers/wallet.py`
- [Top-up API](https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/topups.py): `transit-link/app/routers/topups.py`
- [Tap API](https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/taps.py): `transit-link/app/routers/taps.py`
- [Operator API](https://github.com/smith-89/transit-link/blob/main/transit-link/app/routers/operator.py): `transit-link/app/routers/operator.py`
- [Tokens and access](https://github.com/smith-89/transit-link/blob/main/transit-link/app/security.py): `transit-link/app/security.py`

### Fare and wallet

- [Tap processing](https://github.com/smith-89/transit-link/blob/main/transit-link/app/trips.py): `transit-link/app/trips.py`
- [Fare rules](https://github.com/smith-89/transit-link/blob/main/transit-link/app/fares.py): `transit-link/app/fares.py`
- [Wallet ledger](https://github.com/smith-89/transit-link/blob/main/transit-link/app/ledger.py): `transit-link/app/ledger.py`

### Operator operations

- [Service analytics](https://github.com/smith-89/transit-link/blob/main/transit-link/app/analytics.py): `transit-link/app/analytics.py`
- [Fraud scanning](https://github.com/smith-89/transit-link/blob/main/transit-link/app/fraud.py): `transit-link/app/fraud.py`
- [Operator payouts](https://github.com/smith-89/transit-link/blob/main/transit-link/app/payouts.py): `transit-link/app/payouts.py`

### Persistence and integration

- [Domain records](https://github.com/smith-89/transit-link/blob/main/transit-link/app/models.py): `transit-link/app/models.py`
- [Database sessions](https://github.com/smith-89/transit-link/blob/main/transit-link/app/db.py): `transit-link/app/db.py`
- [Transit data store](https://github.com/smith-89/transit-link/blob/main/transit-link/app/db.py): `transit-link/app/db.py`
- [M-Pesa client](https://github.com/smith-89/transit-link/blob/main/transit-link/app/mpesa.py): `transit-link/app/mpesa.py`
- [Demo data setup](https://github.com/smith-89/transit-link/blob/main/transit-link/app/seed.py): `transit-link/app/seed.py`

### Other components

- **Rider**
- **M-Pesa Daraja**

## Connections

- Rider → Rider app: uses
- Rider app → Shared API client: requests
- Validator app → Shared API client: syncs taps
- Operator app → Shared API client: requests
- Login app → Shared API client: requests
- Shared API client → App entry and routing: calls API
- App entry and routing → Authentication API: registers (evidence: `transit-link/app/main.py`)
- App entry and routing → Wallet API: registers (evidence: `transit-link/app/main.py`)
- App entry and routing → Top-up API: registers (evidence: `transit-link/app/main.py`)
- App entry and routing → Tap API: registers (evidence: `transit-link/app/main.py`)
- App entry and routing → Operator API: registers (evidence: `transit-link/app/main.py`)
- App entry and routing → Database sessions: initializes (evidence: `transit-link/app/main.py`)
- App entry and routing → Demo data setup: seeds data (evidence: `transit-link/app/main.py`)
- Authentication API → Tokens and access: issues tokens (evidence: `transit-link/app/routers/auth.py`)
- Authentication API → Domain records: reads and writes (evidence: `transit-link/app/routers/auth.py`)
- Wallet API → Wallet ledger: reads balance (evidence: `transit-link/app/routers/wallet.py`)
- Top-up API → M-Pesa client: starts payment (evidence: `transit-link/app/routers/topups.py`)
- Top-up API → Wallet ledger: credits funds (evidence: `transit-link/app/routers/topups.py`)
- Top-up API → Domain records: records top-up (evidence: `transit-link/app/routers/topups.py`)
- M-Pesa client → M-Pesa Daraja: requests payment
- Tap API → Tap processing: processes taps (evidence: `transit-link/app/routers/taps.py`)
- Tap processing → Fare rules: checks fares (evidence: `transit-link/app/trips.py`)
- Tap processing → Wallet ledger: debits and refunds (evidence: `transit-link/app/trips.py`)
- Tap processing → Tokens and access: decodes pass (evidence: `transit-link/app/trips.py`)
- Operator API → Service analytics: summarizes service (evidence: `transit-link/app/routers/operator.py`)
- Operator API → Fraud scanning: scans trips (evidence: `transit-link/app/routers/operator.py`)
- Operator API → Operator payouts: runs payout (evidence: `transit-link/app/routers/operator.py`)
- Operator API → Tap processing: closes stale trips (evidence: `transit-link/app/routers/operator.py`)
- Database sessions → Transit data store: connects (evidence: `transit-link/app/db.py`)
- Database sessions → Domain records: creates schema (evidence: `transit-link/app/db.py`)
- Demo data setup → Wallet ledger: posts demo funds (evidence: `transit-link/app/seed.py`)
- Demo data setup → Fare rules: sets fares (evidence: `transit-link/app/seed.py`)