# aryankb/google-hackathon architecture

> Architecture diagram of the GitHub repository aryankb/google-hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aryankb/google-hackathon
- Repository: https://github.com/aryankb/google-hackathon

## Overview

##### Main Components

A. Core Services Layer:
- Location Intelligence Service (map.py, geocoding.py, highway.py)
- Demand Forecasting Service (tasks.py)
- Customer Experience Service (agents.py)
- Data Scraping Service (scrap.py, selen.py)

B. API Layer:
- FastAPI Application (fastapi_app.py, api.py)
- Schema Definitions (schemas.py)

C. Data Layer:
- Database Service (database.py, tables.py)
- Data Storage (saved.db)

D. Utility Layer:
- Tools and Helpers (tools.py)
- Clustering Logic (cluster.py)
- Crew Management (crew.py)

##### Component Relationships

**[External Services] ←→ [API Layer] ←→ [Core Services] ←→ [Data Layer]**
- ↑                     ↑              ↑                ↑
- ┴──────────────┴────────────────┘
- [Utility Layer]

##### Specific Elements

A. External Interfaces:
- Web Scraping Endpoints
- Geocoding Services
- Highway/Road Data Sources
- AI/ML Services (for chatbot)

B. Process Flows:
1. Location Analysis Flow:
- Geocoding → Clustering → Highway Analysis → Location Scoring

2. Demand Forecasting Flow:
- Data Scraping → Sales Analysis → Festive Calendar → AI Processing

3. Customer Experience Flow:
- User Input → Chatbot → Product Search → Recommendations

##### Important Details to Highlight

A. Integration Points:
- Database Connections
- External API Calls
- AI Agent Interactions

B. Data Flows:
- Location Data Processing
- Sales Data Analysis
- Customer Interaction Paths

C. Key Technologies:
- FastAPI
- SQLite Database
- AI Agents (presumably using Gemini)
- Selenium (for web scraping)

##### Architectural Patterns to Emphasize

- Modular Design: Show clear separation between different functional modules
- Service-Oriented: Highlight independent services working together
- Data-Driven: Emphasize the role of data processing and analysis

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef external fill:#6495ED,stroke:#333,stroke-width:2px
    classDef core fill:#90EE90,stroke:#333,stroke-width:2px
    classDef data fill:#FFD700,stroke:#333,stroke-width:2px
    classDef api fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef utility fill:#FFA500,stroke:#333,stroke-width:2px

    %% External Services
    subgraph External["External Services"]
        GEO["Geocoding Services"]:::external
        SCRAPE["Web Scraping Endpoints"]:::external
        HIGHWAY["Highway Data Sources"]:::external
        AI["AI/ML Services"]:::external
    end

    %% API Layer
    subgraph APILayer["API Layer"]
        FAPI["FastAPI Application"]:::api
        SCHEMA["Schema Definitions"]:::api
        API["API Endpoints"]:::api
    end

    %% Core Services
    subgraph CoreServices["Core Services Layer"]
        LIS["Location Intelligence Service"]:::core
        DFS["Demand Forecasting Service"]:::core
        CES["Customer Experience Service"]:::core
        DSS["Data Scraping Service"]:::core
    end

    %% Data Layer
    subgraph DataLayer["Data Layer"]
        DB["Database Service"]:::data
        TABLES["Database Tables"]:::data
        STORAGE["Data Storage"]:::data
    end

    %% Utility Layer
    subgraph UtilityLayer["Utility Layer"]
        TOOLS["Tools and Helpers"]:::utility
        CLUSTER["Clustering Logic"]:::utility
        CREW["Crew Management"]:::utility
    end

    %% Relationships
    External --> APILayer
    APILayer --> CoreServices
    CoreServices --> DataLayer
    UtilityLayer --> External
    UtilityLayer --> APILayer
    UtilityLayer --> CoreServices
    UtilityLayer --> DataLayer

    %% Click Events
    click LIS "https://github.com/Aryankb/google-hackathon/blob/main/map.py"
    click DSS "https://github.com/Aryankb/google-hackathon/blob/main/scrap.py"
    click CES "https://github.com/Aryankb/google-hackathon/blob/main/agents.py"
    click DFS "https://github.com/Aryankb/google-hackathon/blob/main/tasks.py"
    click FAPI "https://github.com/Aryankb/google-hackathon/blob/main/fastapi_app.py"
    click API "https://github.com/Aryankb/google-hackathon/blob/main/api.py"
    click SCHEMA "https://github.com/Aryankb/google-hackathon/blob/main/schemas.py"
    click DB "https://github.com/Aryankb/google-hackathon/blob/main/database.py"
    click TABLES "https://github.com/Aryankb/google-hackathon/blob/main/tables.py"
    click STORAGE "https://github.com/Aryankb/google-hackathon/blob/main/saved.db"
    click TOOLS "https://github.com/Aryankb/google-hackathon/blob/main/tools.py"
    click CLUSTER "https://github.com/Aryankb/google-hackathon/blob/main/cluster.py"
    click CREW "https://github.com/Aryankb/google-hackathon/blob/main/crew.py"

    %% Legend
    subgraph Legend
        L1["External Services"]:::external
        L2["Core Services"]:::core
        L3["Data Components"]:::data
        L4["API Components"]:::api
        L5["Utility Components"]:::utility
    end
```
