# harshsaple/let-the-ambulance-pass architecture

> Architecture diagram of the GitHub repository harshsaple/let-the-ambulance-pass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harshsaple/let-the-ambulance-pass
- Repository: https://github.com/harshsaple/let-the-ambulance-pass

## Overview

##### Project type and purpose
- This is a full-stack, web-based “Smart Ambulance Routing System” built with Flask (Python), HTML/CSS/JavaScript, and integrations with external routing APIs (Google Geocoding and INRIX).
- Purpose: Allow dispatchers or users to input an origin and destination, compute the fastest ambulance path, and actively manage traffic along that path in real time.

##### File structure
- Top-level files
- app.py / template.py – main Flask application entry points
- models.py – domain logic, data classes for routes/locations
- call_api.py, geocoding.py, search_places.py, set_api_key.py, accessToken.py – modules for handling API calls, key management, and geocoding
- api_key.txt, encrypted_api_key.bin – API key storage/encryption
- sample.html, script.js – standalone examples or prototypes
- requirements.txt – Python dependencies
- Directories
- static/ – client-side assets (styles.css, script.js)
- templates/ – Jinja2 HTML templates (home.html, index.html)
- venv/ and __pycache__/ – environment and caches

##### README for additional insights
- Describes core components (Geocoding API, INRIX GetRoute/FindRoute APIs, front-end interface).
- Highlights the system’s real-time rerouting, scalability, and future expansion (traffic signal integration, notifications, ML).
- Demonstrates user flow via the Flask demo.

a. Main components
- Client Browser (UI)
– HTML/CSS/JS served from Flask
– Allows user to enter addresses, displays map and route
- Web Server (Flask Application)
– app.py / template.py handle HTTP routes
– Renders templates, serves static assets
- Service Layer (Python modules)
– geocoding.py → converts addresses to lat/long via Google Geocoding API
– call_api.py / search_places.py → queries INRIX APIs for routes and traffic data
– models.py → encapsulates route objects, distance/time calculations
– set_api_key.py, accessToken.py → manage and decrypt API credentials
- External Services
– Google Geocoding API
– INRIX GetRoute and FindRoute APIs
- (Planned) Traffic Infrastructure / Notification Service
– Smart traffic signals, user notification push

b. Relationships and interactions
1. User enters origin/destination in browser → HTTP POST to Flask
2. Flask controller validates input → calls geocoding.py
3. geocoding.py calls Google Geocoding → returns coordinates
4. Flask then invokes call_api.py/search_places.py → fetches optimal route segments and real-time traffic data from INRIX
5. Response combined into model objects → passed to Jinja2 templates
6. Browser renders map and route; client-side script.js may poll or receive WebSocket updates (future) for dynamic rerouting
7. (Future) Web server pushes reroute notifications back to external traffic signal controllers or mobile clients

c. Architectural patterns and design principles
- MVC-style separation:
- Model: models.py, geocoding.py data structures
- View: Jinja2 templates + static assets
- Controller: app.py / template.py routes
- Service abstraction for external API calls
- Secure key management (encrypted_api_key.bin, accessToken.py)
- Scalability considerations: stateless Flask endpoints, modular service layer for easy horizontal scaling

d. Key technologies, frameworks, and libraries
- Flask (web framework)
- Python requests (HTTP client)
- Google Geocoding API
- INRIX Routing APIs (GetRoute, FindRoute)
- HTML5/CSS3/JavaScript for UI
- Jinja2 (templating engine)
- Encryption library for API key handling

##### Detail without over-complication
- Every Python module or group related modules under “Service Layer”
- Distinguish between synchronous requests (HTTP calls) and asynchronous events (future real-time reroute pushes)
- How encrypted_api_key.bin is decrypted at startup by accessToken.py

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        BrowserUI["User Browser UI"]:::frontend
        subgraph "Static & Templates"
            direction TB
            Home["home.html"]:::frontend
            Index["index.html"]:::frontend
            Styles["styles.css"]:::frontend
            FrontScript["script.js"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Flask Web Server"
        direction TB
        FlaskApp["app.py"]:::backend
        TemplatePY["template.py"]:::backend
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        Geo["Geocoding Service\ngeocoding.py"]:::service
        CallAPI["call_api.py"]:::service
        SearchPlaces["search_places.py"]:::service
        Models["Domain Models\nmodels.py"]:::service
    end

    %% Key Management
    subgraph "API Key Management"
        direction TB
        SetKey["set_api_key.py"]:::utility
        AccessTok["accessToken.py"]:::utility
        APIKeyTxt["api_key.txt"]:::vault
        EncryptedKey["encrypted_api_key.bin"]:::vault
    end

    %% External APIs
    subgraph "External APIs"
        direction TB
        GoogleAPI["Google Geocoding API"]:::external
        INRIXAPI["INRIX Routing APIs"]:::external
    end

    %% Future Components
    subgraph "Future Components"
        direction TB
        TrafficSig["Traffic Signal Controllers"]:::external
        Notification["Notification Service"]:::external
    end

    %% Standalone Examples
    SampleHTML["sample.html"]:::frontend
    StandaloneScript["script.js"]:::frontend

    %% Dependencies
    Requirements["requirements.txt"]:::utility

    %% Relationships
    BrowserUI -->|"loads"| Home
    BrowserUI -->|"loads"| Index
    BrowserUI -->|"loads"| Styles
    BrowserUI -->|"loads"| FrontScript
    BrowserUI -->|"POST origin/destination"| FlaskApp

    FlaskApp -->|"renders templates"| Home
    FlaskApp -->|"renders templates"| Index
    TemplatePY -->|"serves static"| Styles
    TemplatePY -->|"serves static"| FrontScript

    FlaskApp -->|"calls"| Geo
    FlaskApp -->|"calls"| CallAPI
    FlaskApp -->|"calls"| SearchPlaces
    FlaskApp -->|"uses"| Models
    FlaskApp -->|"decrypts keys via"| AccessTok
    FlaskApp -->|"depends on"| Requirements

    AccessTok --> APIKeyTxt
    AccessTok --> EncryptedKey
    SetKey --> APIKeyTxt

    Geo -->|"requests /geocode"| GoogleAPI
    CallAPI -->|"GET /getroute"| INRIXAPI
    SearchPlaces -->|"GET /findroute"| INRIXAPI

    FlaskApp -->|"push reroute"| TrafficSig
    FlaskApp -->|"push notification"| Notification

    FlaskApp -.-> SampleHTML
    FlaskApp -.-> StandaloneScript

    %% Click Events
    click Home "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/templates/home.html"
    click Index "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/templates/index.html"
    click Styles "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/static/styles.css"
    click FrontScript "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/static/script.js"
    click FlaskApp "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/app.py"
    click TemplatePY "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/template.py"
    click Geo "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/geocoding.py"
    click CallAPI "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/call_api.py"
    click SearchPlaces "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/search_places.py"
    click Models "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/models.py"
    click SetKey "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/set_api_key.py"
    click AccessTok "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/accessToken.py"
    click APIKeyTxt "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/api_key.txt"
    click EncryptedKey "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/encrypted_api_key.bin"
    click SampleHTML "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/sample.html"
    click StandaloneScript "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/script.js"
    click Requirements "https://github.com/harshsaple/let-the-ambulance-pass/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#90CAF9,stroke-width:1px
    classDef backend fill:#E8F5E9,stroke:#66BB6A,stroke-width:1px
    classDef service fill:#F1F8E9,stroke:#8BC34A,stroke-width:1px
    classDef external fill:#FFF3E0,stroke:#FFB74D,stroke-width:1px
    classDef vault fill:#ECEFF1,stroke:#B0BEC5,stroke-width:1px
    classDef utility fill:#F3E5F5,stroke:#AB47BC,stroke-width:1px
```
