# ahmed-sarhan71/subway-store-locator-with-ai-agent architecture

> Architecture diagram of the GitHub repository ahmed-sarhan71/subway-store-locator-with-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmed-sarhan71/subway-store-locator-with-ai-agent
- Repository: https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent

## Overview

##### Main Components
- Data Ingestion & Processing Pipeline:
- Web Scraper (subway_scrapper.py): Collects raw store data from Subway.
- Data Processing Scripts:
▪ update_store_hours.py – Standardizes operating hours.
▪ parse_and_store_operating_hours.py – Extracts structured time data.
▪ geocode_subway_stores.py – Converts addresses to GPS coordinates using the Google Maps API.
- Database Setup (create_database.py) and SQLite Database (subway_stores.db): Stores all store information.

- Backend Services:
- Subway Stores API (subway_api.py): FastAPI service running on port 8001, serves endpoints for retrieving store data.
- AI Chatbot API (ai_agent_api.py): FastAPI service running on port 8000, handles natural language queries using NVIDIA NIM (LLama3-8B).

- Frontend:
- Streamlit Web Interface (app.py): Provides a UI for interacting with the system and visualizing store data.

- Testing:
- API Test Suite (test_api.py): Verifies functionality and data integrity.

##### Relationships and Data Flow
- Web Scraper gathers raw data which then flows into the processing pipeline.
- Processed data (including geocoded addresses and standardized operating hours) gets stored in the SQLite database.
- The Subway Stores API fetches data from the database to service REST endpoints (like listing stores or searching by location).
- The AI Chatbot API interacts with the database and external NVIDIA LLM for processing natural language inquiries.
- The Streamlit frontend connects to these APIs to present data to the end user.
- External dependencies include:
- Google Maps API (for geocoding) – integrated in the geocode script.
- NVIDIA API (for LLM-based chatbot) – used within the ai_agent_api.py module.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different scripts handle distinct responsibilities (scraping, processing, geocoding, API serving, and UI rendering).
- Modular Design: Individual components and APIs allow for independent execution (e.g., starting both API services separately).
- Integration of Third-Party Services: Clear interactions with external APIs (Google Maps and NVIDIA NIM).
- Data Pipeline Architecture: Sequential flow starting from data collection to transformation and storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Ingestion & Processing Pipeline"
        WS["Web Scraper"] 
        PH["Update Store Hours"]
        PS["Parse & Store Hours"]
        GEO["Geocoding Module"]
    end

    subgraph "Database Layer"
        DB(["SQLite Database"])
    end

    subgraph "Backend Services"
        API1["Subway Stores API (Port 8001)"]
        API2["AI Chatbot API (Port 8000)"]
    end

    subgraph "Frontend"
        FE["Streamlit Frontend (Port 8501)"]
    end

    subgraph "External Services"
        GM["Google Maps API"]
        NV["NVIDIA API"]
    end

    CONF["Environment Config"]
    TS["Testing Suite"]

    %% Data Ingestion Flow
    WS -->|"feeds"#000000| PH
    WS -->|"feeds"#000000| PS
    WS -->|"feeds"#000000| GEO

    %% Data Processing to Database
    PH -->|"stores_to"#000000| DB
    PS -->|"stores_to"#000000| DB
    GEO -->|"stores_to"#000000| DB

    %% API Services accessing the Database
    DB -->|"reads_by"#000000| API1
    DB -->|"reads_by"#000000| API2

    %% Frontend consuming API Services
    FE -->|"calls"#000000| API1
    FE -->|"calls"#000000| API2

    %% External Service Integrations
    GEO -->|"uses"#000000| GM
    API2 -->|"integrates_with"#000000| NV

    %% Environment Configuration influences external integrations
    CONF -->|"configures"#000000| GEO
    CONF -->|"configures"#000000| API2

    %% Testing Suite interacts with Backend Services
    TS -->|"tests"#000000| API1
    TS -->|"tests"#000000| API2

    %% Style Classes Assignment
    class WS,PH,PS,GEO processing
    class DB database
    class API1,API2 api
    class FE frontend
    class GM,NV external
    class TS testing
    class CONF config

    %% Click Events
    click WS "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/subway_scraper.py"
    click PH "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/update_store_hours.py"
    click PS "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/parse_and_store_operating_hours.py"
    click GEO "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/geocode_subway_stores.py"
    click DB "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/create_database.py"
    click DB "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/subway_stores.db"
    click API1 "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/subway_api.py"
    click API2 "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/ai_agent_api.py"
    click FE "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/app.py"
    click TS "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/test_api.py"
    click CONF "https://github.com/ahmed-sarhan71/subway-store-locator-with-ai-agent/blob/main/.env"

    %% Class Definitions
    classDef processing fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef database fill:#F0F0F0,stroke:#606060,stroke-width:2px;
    classDef api fill:#FFF59D,stroke:#FBC02D,stroke-width:2px;
    classDef frontend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef external fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef testing fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
    classDef config fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
```
