# prashant-tech870/the_great_bengaluru_hack architecture

> Architecture diagram of the GitHub repository prashant-tech870/the_great_bengaluru_hack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prashant-tech870/the_great_bengaluru_hack
- Repository: https://github.com/prashant-tech870/the_great_bengaluru_hack

## Overview

##### Project Type & Purpose
- This is a full-stack Flask-based ride-hailing application that focuses on optimizing driver allocation and passenger pickup in NYC using H3 hexagonal geospatial mapping.
- The application provides separate interfaces for drivers, passengers, administrative dashboards, and leaderboards, while utilizing a SQLite database to store driver data and performance metrics.
- It also integrates external services (like Azure Maps for visualizations) and implements algorithms for demand modeling, driver allocation, and reward computations.

##### File Structure
- Notice top-level files such as app.py, run.py, config.py, and supporting scripts (like create_driver_db.py, data_generator.py, etc.) that anchor the Flask application’s startup.
- The “app” directory contains clear subdirectories:
- “models”: Defines data representations and interactions (e.g., database.py, store.py, user.py).
- “routes”: Contains the Flask view functions (e.g., auth.py, main.py, store.py) that manage incoming API endpoints.
- “static” and “templates”: Hold the CSS, JavaScript, and HTML for the various interfaces.
- “socket.py” hints at real-time or bidirectional communication components.

##### Main Components
a. Client Interfaces:
- Main Dashboard (index.html): Shows demand visualization, time slot selection, driver notifications, and statistics.
- Driver Interface (driver_map.html): Provides route guidance, demand awareness, and performance metrics.
- Passenger Interface (passenger_map.html): Offers pickup options, walking routes, and decision support.
- Leaderboard (driver_leaderboard.html): Displays driver ranking and performance summaries.

b. Server & Backend:
- Flask Web Server (app.py, run.py) that initializes the application and configures the routing.
- API Endpoints: Represent endpoints like “/”, “/get_data”, “/send_notifications”, etc.
- Socket component for any real-time messaging if applicable.

c. Business Logic & Models:
- Models directory (database interactions, store handling, user systems) that encapsulate the logic for demand modeling, driver allocations, trust scoring, and overall business rules.
- Data generation and database initialization scripts (create_driver_db.py, data_generator.py).

d. Database:
- SQLite databases (driver_data.db, instance/app.db) that store driver metrics and performance logs.

e. External Services & Integrations:
- Azure Maps API integration for the interactive maps and hexagonal visualization.
- H3 Hexagonal mapping system for geospatial indexing which drives the demand visualization component.

##### Relationships and Data Flows
- Fetching map/demand data.
- Sending notifications and simulation responses.
- Processing passenger decisions.
- Interactions between the Flask routes and the business logic/models:
- Models processing (driver allocation, trust score computation) that then update the database.
- A connection from the application to the external Azure Maps/H3 services, indicating external API calls for geospatial mapping.
- Data flow from simulated scripts (data_generator.py) contributing to initializing and feeding data into the system.

##### Architectural Patterns & Design Principles
- MVC Pattern: The separation of concerns is visible – Flask controllers (routes), models (business logic and database interactions), and views (templates).
- API-based communication: Clearly delineate the endpoints for client-server interactions.
- Modular design: Multiple modules exist for different interfaces (driver, passenger, leaderboard) and system components.
- Emphasis on real-time interaction (via socket.py) if applicable.

##### Elements
- Clear labels for each main component (e.g., “Driver Interface”, “Passenger Interface”, “Flask Server”, “SQLite Database”, “Azure Maps Integration”).
- From client to server (HTTP/API calls).
- From server to database (read/write operations).
- From server to external services (API calls for geospatial functions).
- Side notes or annotations for key technical details (e.g., “H3 Hexagonal Mapping at Resolution 7”, “Real-time driver notifications”, “Trust Score Calculations”).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        CDashboard["Main Dashboard"]:::client
        CDriver["Driver Interface"]:::client
        CPassenger["Passenger Interface"]:::client
        CLeaderboard["Leaderboard"]:::client
    end

    %% Application/Server Layer
    subgraph "Application Layer"
        SFlask["Flask Web Server"]:::server
        SAPI["API Endpoints/Routes"]:::server
        SSocket["Real-Time Communication"]:::server
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        BLogic["Business Logic & Models"]:::business
        BInit["Data Initialization & Generation"]:::business
    end

    %% Data Layer
    subgraph "Data Layer"
        DDB["SQLite Databases"]:::data
    end

    %% External Services
    subgraph "External Services"
        EExternal["Azure Maps & H3 Mapping"]:::external
    end

    %% Connections - Client to Server
    CDashboard -->|"HTTP/API calls"| SFlask
    CDriver -->|"HTTP/API calls"| SFlask
    CPassenger -->|"HTTP/API calls"| SFlask
    CLeaderboard -->|"HTTP/API calls"| SFlask

    %% Connections - Server Internal
    SFlask -->|"Route handling"| SAPI
    SFlask -->|"Real-time messaging"| SSocket
    SFlask -->|"External API calls"| EExternal

    %% Connections - Server to Business Logic
    SAPI -->|"Process request"| BLogic

    %% Connections - Business Logic to Data
    BLogic -->|"DB operations"| DDB
    BInit -->|"Initialize DB"| DDB

    %% Click Events
    click CDashboard "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/templates/index.html"
    click CDashboard "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app/templates/dashboard/index.html"
    click CDashboard "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app/templates/dashboard/ride_status.html"
    click CDriver "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/templates/driver_map.html"
    click CPassenger "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/templates/passenger_map.html"
    click CPassenger "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/templates/passenger_decision.html"
    click CLeaderboard "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/templates/driver_leaderboard.html"
    click SFlask "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app.py"
    click SFlask "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/run.py"
    click SAPI "https://github.com/prashant-tech870/the_great_bengaluru_hack/tree/main/app/routes"
    click SAPI "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app/routes/auth.py"
    click SAPI "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app/routes/main.py"
    click SAPI "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app/routes/store.py"
    click SSocket "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app/socket.py"
    click BLogic "https://github.com/prashant-tech870/the_great_bengaluru_hack/tree/main/app/models"
    click BLogic "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app/models/database.py"
    click BLogic "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app/models/store.py"
    click BLogic "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/app/models/user.py"
    click BInit "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/create_driver_db.py"
    click BInit "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/data_generator.py"
    click DDB "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/driver_data.db"
    click DDB "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/instance/app.db"
    click EExternal "https://github.com/prashant-tech870/the_great_bengaluru_hack/blob/main/config.py"

    %% Styles
    classDef client fill:#FDEDEC,stroke:#333,stroke-width:2px;
    classDef server fill:#E8F8F5,stroke:#333,stroke-width:2px;
    classDef business fill:#FCF3CF,stroke:#333,stroke-width:2px;
    classDef data fill:#E8DAEF,stroke:#333,stroke-width:2px;
    classDef external fill:#D6EAF8,stroke:#333,stroke-width:2px;
```
