# kwamegilbert/nframa architecture

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

- Interactive diagram: https://gitdiagram.com/kwamegilbert/nframa
- Repository: https://github.com/kwamegilbert/nframa

## Overview

Nframa is a fixed-route ride-platform API: riders and drivers use admin-defined corridors and scheduled trips, with supporting identity, verification, wallet/payment, safety, review, and notification capabilities. The main request flow is HTTP routing through validation/authentication into controllers, which coordinate domain models and services backed by PostgreSQL. The graph includes README-documented capabilities whose implementation was not sampled; those branches are shown at subsystem level. Source excerpts and index references support the depicted internal links; unsampled details are omitted rather than inferred.

Main entry points: [`src/routes/index.ts`](https://github.com/kwamegilbert/nframa/blob/main/src/routes/index.ts) (Route registry), [`src/controllers/trip.controller.ts`](https://github.com/kwamegilbert/nframa/blob/main/src/controllers/trip.controller.ts) (Trip lifecycle), [`src/models/BaseModel.ts`](https://github.com/kwamegilbert/nframa/blob/main/src/models/BaseModel.ts) (Domain models), [`src/controllers/review.controller.ts`](https://github.com/kwamegilbert/nframa/blob/main/src/controllers/review.controller.ts) (Trip reviews)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_http_api["HTTP API<br/>[app.ts]"]
  node_route_registry["Route registry<br/>[index.ts]"]
  node_auth_middleware["Authentication<br/>[authenticate.ts]"]
  node_permission_middleware["Permission checks<br/>[authorize.ts]"]
  node_validation["Request validation<br/>[validate.ts]"]
  node_error_response["Error responses<br/>[errorHandler.ts]"]
end

subgraph group_rides["Ride operations"]
  node_driver_commutes["Driver commutes"]
  node_trip_workflow["Trip lifecycle<br/>[trip.controller.ts]"]
  node_fare_calculation["Fare calculation<br/>[fare.service.ts]"]
  node_route_estimates["Route estimates<br/>[maps.service.ts]"]
  node_trip_records["Trip records<br/>[trip.model.ts]"]
  node_reviews["Trip reviews"]
  node_safety["SOS incidents"]
end

subgraph group_accounts["Accounts and trust"]
  node_auth_flow["Sign-in and sessions<br/>[auth.controller.ts]"]
  node_user_management["User management<br/>[user.controller.ts]"]
  node_verification["Driver verification"]
end

subgraph group_platform["Data and services"]
  node_wallet_payments["Wallet and payments<br/>[wallet.service.ts]"]
  node_notifications["Notifications"]
  node_realtime["Socket events<br/>[socket.service.ts]"]
  node_audit["Activity audit"]
  node_data_models["Domain models<br/>[BaseModel.ts]"]
  node_database[("PostgreSQL")]
end

node_rider_driver(("Riders and drivers"))
node_payment_gateway["Paystack"]

node_rider_driver -->|"uses"| node_http_api
node_http_api -->|"mounts routes"| node_route_registry
node_route_registry -->|"routes trips"| node_trip_workflow
node_route_registry -.->|"routes auth"| node_auth_flow
node_route_registry -->|"routes users"| node_user_management
node_route_registry -->|"routes verification"| node_verification
node_route_registry -->|"routes reviews"| node_reviews
node_route_registry -.->|"routes commutes"| node_driver_commutes
node_route_registry -.->|"routes SOS"| node_safety
node_route_registry -->|"applies authentication"| node_auth_middleware
node_route_registry -->|"validates requests"| node_validation
node_trip_workflow -->|"checks permissions"| node_permission_middleware
node_permission_middleware -->|"queries role permissions"| node_data_models
node_trip_workflow -->|"manages trips"| node_trip_records
node_trip_workflow -->|"loads commutes"| node_driver_commutes
node_trip_workflow -->|"uses fares"| node_fare_calculation
node_trip_workflow -->|"requests route"| node_route_estimates
node_trip_workflow -->|"emits trip events"| node_realtime
node_trip_workflow -->|"records activity"| node_audit
node_reviews -->|"loads trip"| node_trip_records
node_reviews -->|"records activity"| node_audit
node_reviews -->|"finds user"| node_user_management
node_auth_flow -->|"uses account models"| node_data_models
node_user_management -->|"uses user models"| node_data_models
node_verification -->|"uses verification models"| node_data_models
node_verification -->|"sends notices"| node_notifications
node_user_management -->|"records activity"| node_audit
node_data_models -->|"reads and writes"| node_database
node_trip_records -->|"uses fare logic"| node_fare_calculation
node_wallet_payments -.->|"processes payments"| node_payment_gateway
node_http_api -->|"handles errors"| node_error_response

click node_http_api "https://github.com/kwamegilbert/nframa/blob/main/src/app.ts"
click node_route_registry "https://github.com/kwamegilbert/nframa/blob/main/src/routes/index.ts"
click node_auth_middleware "https://github.com/kwamegilbert/nframa/blob/main/src/middlewares/authenticate.ts"
click node_permission_middleware "https://github.com/kwamegilbert/nframa/blob/main/src/middlewares/authorize.ts"
click node_validation "https://github.com/kwamegilbert/nframa/blob/main/src/middlewares/validate.ts"
click node_auth_flow "https://github.com/kwamegilbert/nframa/blob/main/src/controllers/auth.controller.ts"
click node_user_management "https://github.com/kwamegilbert/nframa/blob/main/src/controllers/user.controller.ts"
click node_driver_commutes "https://github.com/kwamegilbert/nframa/blob/main/src/controllers/driverCommute.controller.ts"
click node_trip_workflow "https://github.com/kwamegilbert/nframa/blob/main/src/controllers/trip.controller.ts"
click node_fare_calculation "https://github.com/kwamegilbert/nframa/blob/main/src/services/fare.service.ts"
click node_route_estimates "https://github.com/kwamegilbert/nframa/blob/main/src/services/maps.service.ts"
click node_trip_records "https://github.com/kwamegilbert/nframa/blob/main/src/models/trip.model.ts"
click node_verification "https://github.com/kwamegilbert/nframa/blob/main/src/controllers/verification.controller.ts"
click node_reviews "https://github.com/kwamegilbert/nframa/blob/main/src/controllers/review.controller.ts"
click node_safety "https://github.com/kwamegilbert/nframa/blob/main/src/controllers/sosIncident.controller.ts"
click node_wallet_payments "https://github.com/kwamegilbert/nframa/blob/main/src/services/wallet.service.ts"
click node_notifications "https://github.com/kwamegilbert/nframa/blob/main/src/services/notification.service.ts"
click node_realtime "https://github.com/kwamegilbert/nframa/blob/main/src/services/socket.service.ts"
click node_audit "https://github.com/kwamegilbert/nframa/blob/main/src/services/activityLog.service.ts"
click node_data_models "https://github.com/kwamegilbert/nframa/blob/main/src/models/BaseModel.ts"
click node_error_response "https://github.com/kwamegilbert/nframa/blob/main/src/middlewares/errorHandler.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_http_api,node_route_registry,node_auth_middleware,node_permission_middleware,node_validation,node_error_response toneBlue
class node_driver_commutes,node_trip_workflow,node_fare_calculation,node_route_estimates,node_trip_records,node_reviews,node_safety toneAmber
class node_auth_flow,node_user_management,node_verification toneMint
class node_wallet_payments,node_notifications,node_realtime,node_audit,node_data_models,node_database toneRose
class node_rider_driver,node_payment_gateway toneIndigo
```

## Components

### API and access

- [HTTP API](https://github.com/kwamegilbert/nframa/blob/main/src/app.ts): `src/app.ts`
- [Route registry](https://github.com/kwamegilbert/nframa/blob/main/src/routes/index.ts): `src/routes/index.ts`
- [Authentication](https://github.com/kwamegilbert/nframa/blob/main/src/middlewares/authenticate.ts): `src/middlewares/authenticate.ts`
- [Permission checks](https://github.com/kwamegilbert/nframa/blob/main/src/middlewares/authorize.ts): `src/middlewares/authorize.ts`
- [Request validation](https://github.com/kwamegilbert/nframa/blob/main/src/middlewares/validate.ts): `src/middlewares/validate.ts`
- [Error responses](https://github.com/kwamegilbert/nframa/blob/main/src/middlewares/errorHandler.ts): `src/middlewares/errorHandler.ts`

### Ride operations

- [Driver commutes](https://github.com/kwamegilbert/nframa/blob/main/src/controllers/driverCommute.controller.ts): `src/controllers/driverCommute.controller.ts`
- [Trip lifecycle](https://github.com/kwamegilbert/nframa/blob/main/src/controllers/trip.controller.ts): `src/controllers/trip.controller.ts`
- [Fare calculation](https://github.com/kwamegilbert/nframa/blob/main/src/services/fare.service.ts): `src/services/fare.service.ts`
- [Route estimates](https://github.com/kwamegilbert/nframa/blob/main/src/services/maps.service.ts): `src/services/maps.service.ts`
- [Trip records](https://github.com/kwamegilbert/nframa/blob/main/src/models/trip.model.ts): `src/models/trip.model.ts`
- [Trip reviews](https://github.com/kwamegilbert/nframa/blob/main/src/controllers/review.controller.ts): `src/controllers/review.controller.ts`
- [SOS incidents](https://github.com/kwamegilbert/nframa/blob/main/src/controllers/sosIncident.controller.ts): `src/controllers/sosIncident.controller.ts`

### Accounts and trust

- [Sign-in and sessions](https://github.com/kwamegilbert/nframa/blob/main/src/controllers/auth.controller.ts): `src/controllers/auth.controller.ts`
- [User management](https://github.com/kwamegilbert/nframa/blob/main/src/controllers/user.controller.ts): `src/controllers/user.controller.ts`
- [Driver verification](https://github.com/kwamegilbert/nframa/blob/main/src/controllers/verification.controller.ts): `src/controllers/verification.controller.ts`

### Data and services

- [Wallet and payments](https://github.com/kwamegilbert/nframa/blob/main/src/services/wallet.service.ts): `src/services/wallet.service.ts`
- [Notifications](https://github.com/kwamegilbert/nframa/blob/main/src/services/notification.service.ts): `src/services/notification.service.ts`
- [Socket events](https://github.com/kwamegilbert/nframa/blob/main/src/services/socket.service.ts): `src/services/socket.service.ts`
- [Activity audit](https://github.com/kwamegilbert/nframa/blob/main/src/services/activityLog.service.ts): `src/services/activityLog.service.ts`
- [Domain models](https://github.com/kwamegilbert/nframa/blob/main/src/models/BaseModel.ts): `src/models/BaseModel.ts`
- **PostgreSQL**

### Other components

- **Riders and drivers**
- **Paystack**

## Connections

- Riders and drivers → HTTP API: uses
- HTTP API → Route registry: mounts routes (evidence: `src/app.ts`)
- Route registry → Trip lifecycle: routes trips
- Route registry → Sign-in and sessions: routes auth
- Route registry → User management: routes users
- Route registry → Driver verification: routes verification
- Route registry → Trip reviews: routes reviews
- Route registry → Driver commutes: routes commutes
- Route registry → SOS incidents: routes SOS
- Route registry → Authentication: applies authentication
- Route registry → Request validation: validates requests
- Trip lifecycle → Permission checks: checks permissions (evidence: `src/controllers/trip.controller.ts`)
- Permission checks → Domain models: queries role permissions (evidence: `src/middlewares/authorize.ts`)
- Trip lifecycle → Trip records: manages trips (evidence: `src/controllers/trip.controller.ts`)
- Trip lifecycle → Driver commutes: loads commutes (evidence: `src/controllers/trip.controller.ts`)
- Trip lifecycle → Fare calculation: uses fares (evidence: `src/controllers/trip.controller.ts`)
- Trip lifecycle → Route estimates: requests route (evidence: `src/controllers/trip.controller.ts`)
- Trip lifecycle → Socket events: emits trip events (evidence: `src/controllers/trip.controller.ts`)
- Trip lifecycle → Activity audit: records activity (evidence: `src/controllers/trip.controller.ts`)
- Trip reviews → Trip records: loads trip (evidence: `src/controllers/review.controller.ts`)
- Trip reviews → Activity audit: records activity (evidence: `src/controllers/review.controller.ts`)
- Trip reviews → User management: finds user (evidence: `src/controllers/review.controller.ts`)
- Sign-in and sessions → Domain models: uses account models (evidence: `src/controllers/auth.controller.ts`)
- User management → Domain models: uses user models (evidence: `src/controllers/user.controller.ts`)
- Driver verification → Domain models: uses verification models (evidence: `src/controllers/verification.controller.ts`)
- Driver verification → Notifications: sends notices (evidence: `src/controllers/verification.controller.ts`)
- User management → Activity audit: records activity (evidence: `src/controllers/user.controller.ts`)
- Domain models → PostgreSQL: reads and writes (evidence: `src/models/BaseModel.ts`)
- Trip records → Fare calculation: uses fare logic (evidence: `src/models/trip.model.ts`)
- Wallet and payments → Paystack: processes payments
- HTTP API → Error responses: handles errors (evidence: `src/app.ts`)
