# freebus-co-il/freebus architecture

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

- Interactive diagram: https://gitdiagram.com/freebus-co-il/freebus
- Repository: https://github.com/freebus-co-il/freebus

## Overview

FreeBus is an Israeli public-transit trip planner. Riders search for stops or places, request an A→B itinerary, and view walking, transfer, departure, and available live-delay information in the Expo app. GTFS ingestion builds the database consumed by the API; the API’s RAPTOR index and route handlers serve planning requests, with optional Valhalla walking and Photon/Google geocoding. The README establishes the service boundaries; source-index references and excerpts support selected internal links, but many route and app details were not sampled.

Main entry points: [`api/src/routes/plan.ts`](https://github.com/freebus-co-il/freebus/blob/main/api/src/routes/plan.ts) (Journey planning route), [`api/src/server.ts`](https://github.com/freebus-co-il/freebus/blob/main/api/src/server.ts) (HTTP server and routes), [`api/src/index.ts`](https://github.com/freebus-co-il/freebus/blob/main/api/src/index.ts) (API service), [`gtfs/src/pipeline/importFeed.ts`](https://github.com/freebus-co-il/freebus/blob/main/gtfs/src/pipeline/importFeed.ts) (Feed importer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["GTFS ingestion"]
  node_gtfs_sched["Import scheduler<br/>[scheduler.ts]"]
  node_feed["GTFS feed client<br/>[client.ts]"]
  node_import["Feed importer<br/>[importFeed.ts]"]
  node_gtfs_db[("Versioned GTFS database<br/>[swap.ts]")]
end

subgraph group_api["Planning API"]
  node_api_entry["API service<br/>[index.ts]"]
  node_api_server["HTTP server and routes<br/>[server.ts]"]
  node_plan_route["Journey planning route<br/>[plan.ts]"]
  node_transit_index["Timetable index<br/>[index.ts]"]
  node_index_manager["Index manager<br/>[manager.ts]"]
  node_db_bundle["GTFS database access<br/>[bundle.ts]"]
  node_walk_router["Walking router<br/>[valhalla.ts]"]
  node_geocoder["Geocoding integration<br/>[buildGeocoder.ts]"]
end

subgraph group_realtime["Realtime data"]
  node_realtime_runtime["Realtime runtime<br/>[wiring.ts]"]
  node_realtime_poller["Feed poller<br/>[poller.ts]"]
  node_realtime_store["Realtime store<br/>[store.ts]"]
end

subgraph group_mobile["Mobile app"]
  node_app["Expo client<br/>[index.tsx]"]
  node_app_api["API client<br/>[client.ts]"]
  node_journey_state["Live journey state"]
end

subgraph group_integrations["External services"]
  node_valhalla["Valhalla"]
  node_geocode_services["Photon or Google"]
  node_mot_feed["Ministry realtime feed"]
end

node_rider(("Rider"))

node_rider -->|"searches and plans"| node_app
node_app -.->|"requests data"| node_app_api
node_app_api -->|"calls over HTTP"| node_api_server
node_api_server -->|"routes requests"| node_plan_route
node_plan_route -->|"plans with RAPTOR"| node_transit_index
node_plan_route -->|"resolves walk geometry"| node_walk_router
node_index_manager -->|"builds database bundle"| node_db_bundle
node_index_manager -->|"builds timetable index"| node_transit_index
node_api_entry -->|"creates manager"| node_index_manager
node_api_entry -->|"starts service"| node_api_server
node_api_entry -->|"creates runtime"| node_realtime_runtime
node_realtime_runtime -.->|"creates poller"| node_realtime_poller
node_realtime_poller -.->|"updates predictions"| node_realtime_store
node_plan_route -->|"annotates itineraries"| node_realtime_store
node_gtfs_sched -->|"runs imports"| node_import
node_import -->|"fetches feed"| node_feed
node_import -->|"builds and swaps"| node_gtfs_db
node_gtfs_db -->|"database read source"| node_db_bundle
node_walk_router -->|"requests routes"| node_valhalla
node_api_server -->|"configures geocoder"| node_geocoder
node_geocoder -->|"geocodes places"| node_geocode_services
node_realtime_poller -->|"polls when configured"| node_mot_feed
node_journey_state -.->|"supports live journeys"| node_app

click node_gtfs_sched "https://github.com/freebus-co-il/freebus/blob/main/gtfs/src/scheduler.ts"
click node_feed "https://github.com/freebus-co-il/freebus/blob/main/gtfs/src/feed/client.ts"
click node_import "https://github.com/freebus-co-il/freebus/blob/main/gtfs/src/pipeline/importFeed.ts"
click node_gtfs_db "https://github.com/freebus-co-il/freebus/blob/main/gtfs/src/db/swap.ts"
click node_api_entry "https://github.com/freebus-co-il/freebus/blob/main/api/src/index.ts"
click node_api_server "https://github.com/freebus-co-il/freebus/blob/main/api/src/server.ts"
click node_plan_route "https://github.com/freebus-co-il/freebus/blob/main/api/src/routes/plan.ts"
click node_transit_index "https://github.com/freebus-co-il/freebus/blob/main/api/src/transit/index.ts"
click node_index_manager "https://github.com/freebus-co-il/freebus/blob/main/api/src/transit/manager.ts"
click node_db_bundle "https://github.com/freebus-co-il/freebus/blob/main/api/src/db/bundle.ts"
click node_walk_router "https://github.com/freebus-co-il/freebus/blob/main/api/src/walking/valhalla.ts"
click node_geocoder "https://github.com/freebus-co-il/freebus/blob/main/api/src/geocode/buildGeocoder.ts"
click node_realtime_runtime "https://github.com/freebus-co-il/freebus/blob/main/api/src/realtime/wiring.ts"
click node_realtime_poller "https://github.com/freebus-co-il/freebus/blob/main/api/src/realtime/poller.ts"
click node_realtime_store "https://github.com/freebus-co-il/freebus/blob/main/api/src/realtime/store.ts"
click node_app "https://github.com/freebus-co-il/freebus/blob/main/app/src/app/(tabs)/index.tsx"
click node_app_api "https://github.com/freebus-co-il/freebus/blob/main/app/src/api/client.ts"
click node_journey_state "https://github.com/freebus-co-il/freebus/blob/main/app/src/features/journey/journey-context.tsx"

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_gtfs_sched,node_feed,node_import,node_gtfs_db toneBlue
class node_api_entry,node_api_server,node_plan_route,node_transit_index,node_index_manager,node_db_bundle,node_walk_router,node_geocoder toneAmber
class node_realtime_runtime,node_realtime_poller,node_realtime_store toneMint
class node_app,node_app_api,node_journey_state toneRose
class node_valhalla,node_geocode_services,node_mot_feed,node_rider toneIndigo
```

## Components

### GTFS ingestion

- [Import scheduler](https://github.com/freebus-co-il/freebus/blob/main/gtfs/src/scheduler.ts): `gtfs/src/scheduler.ts`
- [GTFS feed client](https://github.com/freebus-co-il/freebus/blob/main/gtfs/src/feed/client.ts): `gtfs/src/feed/client.ts`
- [Feed importer](https://github.com/freebus-co-il/freebus/blob/main/gtfs/src/pipeline/importFeed.ts): `gtfs/src/pipeline/importFeed.ts`
- [Versioned GTFS database](https://github.com/freebus-co-il/freebus/blob/main/gtfs/src/db/swap.ts): `gtfs/src/db/swap.ts`

### Planning API

- [API service](https://github.com/freebus-co-il/freebus/blob/main/api/src/index.ts): `api/src/index.ts`
- [HTTP server and routes](https://github.com/freebus-co-il/freebus/blob/main/api/src/server.ts): `api/src/server.ts`
- [Journey planning route](https://github.com/freebus-co-il/freebus/blob/main/api/src/routes/plan.ts): `api/src/routes/plan.ts`
- [Timetable index](https://github.com/freebus-co-il/freebus/blob/main/api/src/transit/index.ts): `api/src/transit/index.ts`
- [Index manager](https://github.com/freebus-co-il/freebus/blob/main/api/src/transit/manager.ts): `api/src/transit/manager.ts`
- [GTFS database access](https://github.com/freebus-co-il/freebus/blob/main/api/src/db/bundle.ts): `api/src/db/bundle.ts`
- [Walking router](https://github.com/freebus-co-il/freebus/blob/main/api/src/walking/valhalla.ts): `api/src/walking/valhalla.ts`
- [Geocoding integration](https://github.com/freebus-co-il/freebus/blob/main/api/src/geocode/buildGeocoder.ts): `api/src/geocode/buildGeocoder.ts`

### Realtime data

- [Realtime runtime](https://github.com/freebus-co-il/freebus/blob/main/api/src/realtime/wiring.ts): `api/src/realtime/wiring.ts`
- [Feed poller](https://github.com/freebus-co-il/freebus/blob/main/api/src/realtime/poller.ts): `api/src/realtime/poller.ts`
- [Realtime store](https://github.com/freebus-co-il/freebus/blob/main/api/src/realtime/store.ts): `api/src/realtime/store.ts`

### Mobile app

- [Expo client](https://github.com/freebus-co-il/freebus/blob/main/app/src/app/(tabs)/index.tsx): `app/src/app/(tabs)/index.tsx`
- [API client](https://github.com/freebus-co-il/freebus/blob/main/app/src/api/client.ts): `app/src/api/client.ts`
- [Live journey state](https://github.com/freebus-co-il/freebus/blob/main/app/src/features/journey/journey-context.tsx): `app/src/features/journey/journey-context.tsx`

### External services

- **Valhalla**
- **Photon or Google**
- **Ministry realtime feed**

### Other components

- **Rider**

## Connections

- Rider → Expo client: searches and plans (evidence: `README.md`)
- Expo client → API client: requests data
- API client → HTTP server and routes: calls over HTTP (evidence: `README.md`)
- HTTP server and routes → Journey planning route: routes requests (evidence: `api/src/server.ts`)
- Journey planning route → Timetable index: plans with RAPTOR (evidence: `api/src/routes/plan.ts`)
- Journey planning route → Walking router: resolves walk geometry (evidence: `api/src/routes/plan.ts`)
- Index manager → GTFS database access: builds database bundle (evidence: `api/src/transit/manager.ts`)
- Index manager → Timetable index: builds timetable index (evidence: `api/src/transit/manager.ts`)
- API service → Index manager: creates manager (evidence: `api/src/index.ts`)
- API service → HTTP server and routes: starts service (evidence: `api/src/index.ts`)
- API service → Realtime runtime: creates runtime (evidence: `api/src/index.ts`)
- Realtime runtime → Feed poller: creates poller
- Feed poller → Realtime store: updates predictions (evidence: `api/src/realtime/poller.ts`)
- Journey planning route → Realtime store: annotates itineraries (evidence: `api/src/routes/plan.ts`)
- Import scheduler → Feed importer: runs imports (evidence: `gtfs/src/scheduler.ts`)
- Feed importer → GTFS feed client: fetches feed (evidence: `gtfs/src/pipeline/importFeed.ts`)
- Feed importer → Versioned GTFS database: builds and swaps (evidence: `gtfs/src/pipeline/importFeed.ts`)
- Versioned GTFS database → GTFS database access: database read source (evidence: `README.md`)
- Walking router → Valhalla: requests routes (evidence: `README.md`)
- HTTP server and routes → Geocoding integration: configures geocoder (evidence: `api/src/server.ts`)
- Geocoding integration → Photon or Google: geocodes places (evidence: `README.md`)
- Feed poller → Ministry realtime feed: polls when configured (evidence: `README.md`)
- Live journey state → Expo client: supports live journeys
