How ahmed-sarhan71/subway-store-locator-with-ai-agent works
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.