# tiburon-0/ride-share-system architecture

> Architecture diagram of the GitHub repository tiburon-0/ride-share-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tiburon-0/ride-share-system
- Repository: https://github.com/tiburon-0/ride-share-system

## Overview

This is a ride-hailing simulation whose main workflow loads rider, driver, and location data; filters and ranks available drivers using preferences and graph distances; creates and advances a trip; then records matching and trip outcomes. The README documents payment and mutual-rating capabilities alongside this flow. The excerpts show the persistence calls and trip lifecycle directly, but do not expose all matching, payment, or rating orchestration, so those links are limited to documented ownership rather than inferred call chains.

Main entry points: [`database_model.py`](https://github.com/tiburon-0/ride-share-system/blob/main/database_model.py) (Mini ORM), [`main.py`](https://github.com/tiburon-0/ride-share-system/blob/main/main.py) (Menu and Orchestration), [`ride.py`](https://github.com/tiburon-0/ride-share-system/blob/main/ride.py) (Trip Lifecycle), [`driver.py`](https://github.com/tiburon-0/ride-share-system/blob/main/driver.py) (Driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Simulation Workflow"]
  node_agent["Dispatch Agent<br/>[agent.py]"]
  node_main["Menu and Orchestration<br/>[main.py]"]
  node_jsondata["JSON Data<br/>[riders.json]"]
end

subgraph group_domain["Ride Domain"]
  node_user["User<br/>[user.py]"]
  node_rider["Rider<br/>[rider.py]"]
  node_driver["Driver<br/>[driver.py]"]
  node_car["Car Types<br/>[car.py]"]
  node_preference["Preferences<br/>[preference.py]"]
  node_billing["Billing Info<br/>[billing_info.py]"]
  node_payment["Payment Methods<br/>[payment_method.py]"]
  node_ride["Trip Lifecycle<br/>[ride.py]"]
  node_rating["Mutual Ratings<br/>[rating.py]"]
end

subgraph group_routing["Matching and Routing"]
  node_matching["Greedy Matching<br/>[main.py]"]
  node_map["City Graph<br/>[map_learning.py]"]
  node_graph["Graph Routing<br/>[graph_model.py]"]
  node_location["Locations<br/>[location.py]"]
end

subgraph group_persistence["Persistence"]
  node_matchlog["Match Audit Log<br/>[matching_log.py]"]
  node_orm["Mini ORM<br/>[database_model.py]"]
  node_dbmanager["SQLite Manager"]
  node_sqlite[("Ride Database<br/>[rideshare.db]")]
end

node_rideractor(("Rider"))

node_rideractor -->|"selects workflow"| node_main
node_main -->|"loads records"| node_jsondata
node_main -->|"requests assignment"| node_matching
node_matching -->|"filters candidates"| node_preference
node_matching -->|"computes distance"| node_graph
node_map -->|"supplies network"| node_graph
node_graph -->|"routes locations"| node_location
node_main -->|"dispatches ride"| node_agent
node_agent -->|"creates trip"| node_ride
node_ride -.->|"supports payment"| node_payment
node_billing -->|"holds methods"| node_payment
node_rider -->|"extends"| node_user
node_driver -->|"extends"| node_user
node_driver -->|"uses car"| node_car
node_matching -->|"records decision"| node_matchlog
node_matchlog -->|"persists through"| node_orm
node_rider -->|"persists through"| node_orm
node_driver -->|"persists through"| node_orm
node_ride -->|"persists through"| node_orm
node_orm -->|"executes queries"| node_dbmanager
node_dbmanager -->|"reads and writes"| node_sqlite
node_ride -.->|"enables mutual rating"| node_rating

click node_user "https://github.com/tiburon-0/ride-share-system/blob/main/user.py"
click node_rider "https://github.com/tiburon-0/ride-share-system/blob/main/rider.py"
click node_driver "https://github.com/tiburon-0/ride-share-system/blob/main/driver.py"
click node_car "https://github.com/tiburon-0/ride-share-system/blob/main/car.py"
click node_preference "https://github.com/tiburon-0/ride-share-system/blob/main/preference.py"
click node_billing "https://github.com/tiburon-0/ride-share-system/blob/main/billing_info.py"
click node_payment "https://github.com/tiburon-0/ride-share-system/blob/main/payment_method.py"
click node_ride "https://github.com/tiburon-0/ride-share-system/blob/main/ride.py"
click node_agent "https://github.com/tiburon-0/ride-share-system/blob/main/agent.py"
click node_rating "https://github.com/tiburon-0/ride-share-system/blob/main/rating.py"
click node_main "https://github.com/tiburon-0/ride-share-system/blob/main/main.py"
click node_jsondata "https://github.com/tiburon-0/ride-share-system/blob/main/riders.json"
click node_matching "https://github.com/tiburon-0/ride-share-system/blob/main/main.py"
click node_map "https://github.com/tiburon-0/ride-share-system/blob/main/map_learning.py"
click node_graph "https://github.com/tiburon-0/ride-share-system/blob/main/graph_model.py"
click node_location "https://github.com/tiburon-0/ride-share-system/blob/main/location.py"
click node_matchlog "https://github.com/tiburon-0/ride-share-system/blob/main/matching_log.py"
click node_orm "https://github.com/tiburon-0/ride-share-system/blob/main/database_model.py"
click node_dbmanager "https://github.com/tiburon-0/ride-share-system/blob/main/database_manager.py"
click node_sqlite "https://github.com/tiburon-0/ride-share-system/blob/main/rideshare.db"

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_agent,node_main,node_jsondata toneBlue
class node_user,node_rider,node_driver,node_car,node_preference,node_billing,node_payment,node_ride,node_rating toneAmber
class node_matching,node_map,node_graph,node_location toneMint
class node_matchlog,node_orm,node_dbmanager,node_sqlite toneRose
class node_rideractor toneIndigo
```

## Components

### Simulation Workflow

- [Dispatch Agent](https://github.com/tiburon-0/ride-share-system/blob/main/agent.py): `agent.py`
- [Menu and Orchestration](https://github.com/tiburon-0/ride-share-system/blob/main/main.py): `main.py`
- [JSON Data](https://github.com/tiburon-0/ride-share-system/blob/main/riders.json): `riders.json`

### Ride Domain

- [User](https://github.com/tiburon-0/ride-share-system/blob/main/user.py): `user.py`
- [Rider](https://github.com/tiburon-0/ride-share-system/blob/main/rider.py): `rider.py`
- [Driver](https://github.com/tiburon-0/ride-share-system/blob/main/driver.py): `driver.py`
- [Car Types](https://github.com/tiburon-0/ride-share-system/blob/main/car.py): `car.py`
- [Preferences](https://github.com/tiburon-0/ride-share-system/blob/main/preference.py): `preference.py`
- [Billing Info](https://github.com/tiburon-0/ride-share-system/blob/main/billing_info.py): `billing_info.py`
- [Payment Methods](https://github.com/tiburon-0/ride-share-system/blob/main/payment_method.py): `payment_method.py`
- [Trip Lifecycle](https://github.com/tiburon-0/ride-share-system/blob/main/ride.py): `ride.py`
- [Mutual Ratings](https://github.com/tiburon-0/ride-share-system/blob/main/rating.py): `rating.py`

### Matching and Routing

- [Greedy Matching](https://github.com/tiburon-0/ride-share-system/blob/main/main.py): `main.py`
- [City Graph](https://github.com/tiburon-0/ride-share-system/blob/main/map_learning.py): `map_learning.py`
- [Graph Routing](https://github.com/tiburon-0/ride-share-system/blob/main/graph_model.py): `graph_model.py`
- [Locations](https://github.com/tiburon-0/ride-share-system/blob/main/location.py): `location.py`

### Persistence

- [Match Audit Log](https://github.com/tiburon-0/ride-share-system/blob/main/matching_log.py): `matching_log.py`
- [Mini ORM](https://github.com/tiburon-0/ride-share-system/blob/main/database_model.py): `database_model.py`
- [SQLite Manager](https://github.com/tiburon-0/ride-share-system/blob/main/database_manager.py): `database_manager.py`
- [Ride Database](https://github.com/tiburon-0/ride-share-system/blob/main/rideshare.db): `rideshare.db`

### Other components

- **Rider**

## Connections

- Rider → Menu and Orchestration: selects workflow
- Menu and Orchestration → JSON Data: loads records
- Menu and Orchestration → Greedy Matching: requests assignment
- Greedy Matching → Preferences: filters candidates
- Greedy Matching → Graph Routing: computes distance
- City Graph → Graph Routing: supplies network
- Graph Routing → Locations: routes locations
- Menu and Orchestration → Dispatch Agent: dispatches ride
- Dispatch Agent → Trip Lifecycle: creates trip
- Trip Lifecycle → Payment Methods: supports payment
- Billing Info → Payment Methods: holds methods
- Rider → User: extends
- Driver → User: extends
- Driver → Car Types: uses car
- Greedy Matching → Match Audit Log: records decision
- Match Audit Log → Mini ORM: persists through
- Rider → Mini ORM: persists through
- Driver → Mini ORM: persists through
- Trip Lifecycle → Mini ORM: persists through
- Mini ORM → SQLite Manager: executes queries
- SQLite Manager → Ride Database: reads and writes
- Trip Lifecycle → Mutual Ratings: enables mutual rating