# jruchsas/bharakoto architecture

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

- Interactive diagram: https://gitdiagram.com/jruchsas/bharakoto
- Repository: https://github.com/jruchsas/bharakoto

## Overview

BharaKoto is a Dhaka commuter web app for comparing realistic and official fares while accounting for route geometry and restricted roads. The main flow runs from the browser’s origin/destination and vehicle selections through fare estimation, which combines fare rules, route services, and active restriction data; the browser also supports place lookup, fare history, and community reports. A separate admin flow manages restricted zones. The README documents several integrations, but some endpoint implementations and UI wiring were not sampled, so those links rely on its architecture description.

Main entry points: [`public/index.php`](https://github.com/jruchsas/bharakoto/blob/main/public/index.php) (Fare map UI), [`config/database.php`](https://github.com/jruchsas/bharakoto/blob/main/config/database.php) (Database connection), [`public/api/places.php`](https://github.com/jruchsas/bharakoto/blob/main/public/api/places.php) (Places API), [`src/FareEstimatorService.php`](https://github.com/jruchsas/bharakoto/blob/main/src/FareEstimatorService.php) (Fare and route engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commute["Commuter experience"]
  node_web["Fare map UI<br/>[index.php]"]
  node_nominatim["Nominatim geocoder"]
  node_barikoi["Barikoi places"]
end

subgraph group_api["Public API"]
  node_estimate_api["Estimate API<br/>[estimate.php]"]
  node_places_api["Places API<br/>[places.php]"]
  node_reverse_api["Reverse geocoder API<br/>[reverse.php]"]
  node_zones_api["Zones API<br/>[zones.php]"]
  node_crowd_api["Community fares API<br/>[crowdsourced.php]"]
  node_history_api["Fare history API<br/>[fare-history.php]"]
end

subgraph group_domain["Fare and routing"]
  node_estimator["Fare and route engine"]
  node_osrm["OSRM routing"]
  node_ors["OpenRouteService"]
  node_weather["Weather service"]
end

subgraph group_zones["Zone management"]
  node_admin["Zone admin UI<br/>[admin-zones.php]"]
  node_ban_seed["Official ban data"]
end

subgraph group_platform["Data and safeguards"]
  node_database["Database connection<br/>[database.php]"]
  node_mysql[("MySQL store")]
  node_rate_limit["Rate limiter<br/>[RateLimiter.php]"]
  node_csrf["CSRF protection<br/>[CsrfProtection.php]"]
  node_node_seed["Dhaka place data"]
end

node_commuter(("Commuter"))

node_commuter -->|"uses"| node_web
node_web -->|"requests estimate"| node_estimate_api
node_web -->|"searches places"| node_places_api
node_web -->|"requests geocoding"| node_reverse_api
node_web -->|"loads zones"| node_zones_api
node_web -->|"submits fares"| node_crowd_api
node_web -->|"loads history"| node_history_api
node_estimate_api -->|"calculates fare"| node_estimator
node_estimator -->|"opens connection"| node_database
node_places_api -->|"opens connection"| node_database
node_reverse_api -->|"opens connection"| node_database
node_zones_api -->|"opens connection"| node_database
node_crowd_api -->|"opens connection"| node_database
node_history_api -->|"opens connection"| node_database
node_database -->|"connects"| node_mysql
node_admin -->|"manages zones"| node_zones_api
node_estimate_api -->|"enforces limits"| node_rate_limit
node_places_api -->|"enforces limits"| node_rate_limit
node_zones_api -->|"validates changes"| node_csrf
node_crowd_api -->|"validates submissions"| node_csrf
node_estimator -->|"requests routes"| node_osrm
node_estimator -.->|"fallback routes"| node_ors
node_estimator -.->|"checks conditions"| node_weather
node_places_api -->|"geocodes fallback"| node_nominatim
node_places_api -.->|"searches optionally"| node_barikoi
node_node_seed -->|"seeds places"| node_mysql
node_ban_seed -->|"seeds restrictions"| node_mysql

click node_web "https://github.com/jruchsas/bharakoto/blob/main/public/index.php"
click node_admin "https://github.com/jruchsas/bharakoto/blob/main/public/admin-zones.php"
click node_estimate_api "https://github.com/jruchsas/bharakoto/blob/main/public/api/estimate.php"
click node_places_api "https://github.com/jruchsas/bharakoto/blob/main/public/api/places.php"
click node_reverse_api "https://github.com/jruchsas/bharakoto/blob/main/public/api/reverse.php"
click node_zones_api "https://github.com/jruchsas/bharakoto/blob/main/public/api/zones.php"
click node_crowd_api "https://github.com/jruchsas/bharakoto/blob/main/public/api/crowdsourced.php"
click node_history_api "https://github.com/jruchsas/bharakoto/blob/main/public/api/fare-history.php"
click node_estimator "https://github.com/jruchsas/bharakoto/blob/main/src/FareEstimatorService.php"
click node_database "https://github.com/jruchsas/bharakoto/blob/main/config/database.php"
click node_rate_limit "https://github.com/jruchsas/bharakoto/blob/main/src/RateLimiter.php"
click node_csrf "https://github.com/jruchsas/bharakoto/blob/main/src/CsrfProtection.php"
click node_node_seed "https://github.com/jruchsas/bharakoto/blob/main/database/seed_expanded_nodes.php"
click node_ban_seed "https://github.com/jruchsas/bharakoto/blob/main/database/apply_official_dmp_bans.php"

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_web,node_nominatim,node_barikoi toneBlue
class node_estimate_api,node_places_api,node_reverse_api,node_zones_api,node_crowd_api,node_history_api toneAmber
class node_estimator,node_osrm,node_ors,node_weather toneMint
class node_admin,node_ban_seed toneRose
class node_database,node_mysql,node_rate_limit,node_csrf,node_node_seed,node_commuter toneIndigo
```

## Components

### Commuter experience

- [Fare map UI](https://github.com/jruchsas/bharakoto/blob/main/public/index.php): `public/index.php`
- **Nominatim geocoder**
- **Barikoi places**

### Public API

- [Estimate API](https://github.com/jruchsas/bharakoto/blob/main/public/api/estimate.php): `public/api/estimate.php`
- [Places API](https://github.com/jruchsas/bharakoto/blob/main/public/api/places.php): `public/api/places.php`
- [Reverse geocoder API](https://github.com/jruchsas/bharakoto/blob/main/public/api/reverse.php): `public/api/reverse.php`
- [Zones API](https://github.com/jruchsas/bharakoto/blob/main/public/api/zones.php): `public/api/zones.php`
- [Community fares API](https://github.com/jruchsas/bharakoto/blob/main/public/api/crowdsourced.php): `public/api/crowdsourced.php`
- [Fare history API](https://github.com/jruchsas/bharakoto/blob/main/public/api/fare-history.php): `public/api/fare-history.php`

### Fare and routing

- [Fare and route engine](https://github.com/jruchsas/bharakoto/blob/main/src/FareEstimatorService.php): `src/FareEstimatorService.php`
- **OSRM routing**
- **OpenRouteService**
- **Weather service**

### Zone management

- [Zone admin UI](https://github.com/jruchsas/bharakoto/blob/main/public/admin-zones.php): `public/admin-zones.php`
- [Official ban data](https://github.com/jruchsas/bharakoto/blob/main/database/apply_official_dmp_bans.php): `database/apply_official_dmp_bans.php`

### Data and safeguards

- [Database connection](https://github.com/jruchsas/bharakoto/blob/main/config/database.php): `config/database.php`
- **MySQL store**
- [Rate limiter](https://github.com/jruchsas/bharakoto/blob/main/src/RateLimiter.php): `src/RateLimiter.php`
- [CSRF protection](https://github.com/jruchsas/bharakoto/blob/main/src/CsrfProtection.php): `src/CsrfProtection.php`
- [Dhaka place data](https://github.com/jruchsas/bharakoto/blob/main/database/seed_expanded_nodes.php): `database/seed_expanded_nodes.php`

### Other components

- **Commuter**

## Connections

- Commuter → Fare map UI: uses (evidence: `README.md`)
- Fare map UI → Estimate API: requests estimate (evidence: `README.md`)
- Fare map UI → Places API: searches places (evidence: `README.md`)
- Fare map UI → Reverse geocoder API: requests geocoding (evidence: `README.md`)
- Fare map UI → Zones API: loads zones (evidence: `README.md`)
- Fare map UI → Community fares API: submits fares (evidence: `README.md`)
- Fare map UI → Fare history API: loads history (evidence: `README.md`)
- Estimate API → Fare and route engine: calculates fare (evidence: `public/api/estimate.php`)
- Fare and route engine → Database connection: opens connection (evidence: `src/FareEstimatorService.php`)
- Places API → Database connection: opens connection (evidence: `public/api/places.php`)
- Reverse geocoder API → Database connection: opens connection (evidence: `public/api/reverse.php`)
- Zones API → Database connection: opens connection (evidence: `public/api/zones.php`)
- Community fares API → Database connection: opens connection (evidence: `public/api/crowdsourced.php`)
- Fare history API → Database connection: opens connection (evidence: `public/api/fare-history.php`)
- Database connection → MySQL store: connects (evidence: `config/database.php`)
- Zone admin UI → Zones API: manages zones (evidence: `public/admin-zones.php`)
- Estimate API → Rate limiter: enforces limits (evidence: `public/api/estimate.php`)
- Places API → Rate limiter: enforces limits (evidence: `public/api/places.php`)
- Zones API → CSRF protection: validates changes (evidence: `public/api/zones.php`)
- Community fares API → CSRF protection: validates submissions (evidence: `public/api/crowdsourced.php`)
- Fare and route engine → OSRM routing: requests routes (evidence: `README.md`)
- Fare and route engine → OpenRouteService: fallback routes (evidence: `README.md`)
- Fare and route engine → Weather service: checks conditions (evidence: `README.md`)
- Places API → Nominatim geocoder: geocodes fallback (evidence: `README.md`)
- Places API → Barikoi places: searches optionally (evidence: `README.md`)
- Dhaka place data → MySQL store: seeds places (evidence: `database/seed_expanded_nodes.php`)
- Official ban data → MySQL store: seeds restrictions (evidence: `database/apply_official_dmp_bans.php`)
