# jotthecode/city-pulse architecture

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

- Interactive diagram: https://gitdiagram.com/jotthecode/city-pulse
- Repository: https://github.com/jotthecode/city-pulse

## Overview

##### Project Type & Purpose
- City Pulse is a full-stack, single-page dashboard application built in Python using Streamlit. Its goal is to provide live, multifaceted city insights (weather, AQI, crime news, tourist sites, Google Trends, AI chat).

##### File Structure Analysis
- Top level:
- app.py – main Streamlit entry point & UI router
- config.py – configuration loader (.env integration)
- requirements.txt / .env – dependency and secret management
- utils/ – a collection of domain-specific modules:
– air_quality.py
– weather.py
– crime.py
– tourist.py
– transport.py
– chatbot.py
– abc (shared helper functions)
- .devcontainer – defines the development environment (VS Code Remote-Containers)
- No internal database; interacting real-time with external APIs

##### README Insights
- Frontend: Streamlit components and HTML/CSS via Streamlit
- Backend: Python modules in utils/ orchestrate API calls
- External APIs:
- OpenWeatherMap (weather + AQI)
- Google Places (tourist)
- News API (crime headlines)
- Pytrends (Google Trends)
- Custom Google Search integration (chatbot)
- Data manipulation libraries: Pandas, Requests

##### Core Components
a. Streamlit UI Layer
– app.py renders pages, layouts, controls
b. Orchestrator & Business Logic
– app.py delegates to utils modules
– config.py provides API keys/endpoints
c. Domain Modules (utils/)
– WeatherService (weather.py)
– AirQualityService (air_quality.py)
– CrimeService (crime.py)
– TouristService (tourist.py)
– TransportService (transport.py)
– TrendsService (pytrends)
– ChatbotService (chatbot.py + Google Search)
– Shared utilities (utils/abc)
d. External Services & APIs
– OpenWeatherMap API
– Google Places API
– News API
– Google Trends (Pytrends)
– Google Search integration

##### Relationships & Data Flow
1. User interacts with Streamlit frontend (app.py).
2. Frontend triggers handler in app.py → calls corresponding utils module method.
3. Module uses config.py to load credentials (.env).
4. Module issues HTTP request to external API.
5. External API returns JSON → utils parses with Pandas/Requests.
6. Data is returned to app.py → transformed into Streamlit charts, tables, text.
7. Results rendered in browser.

##### Architectural Patterns & Principles
- Single-page UI driven by Streamlit (component-based)
- Separation of concerns: UI vs. business logic vs. external integration
- Modular “micro-service” style within a monorepo (each feature in its own Python module)
- Config-driven for API keys and endpoints

##### Essential Elements
- Component boundaries & names (app.py, utils/weather.py, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Streamlit UI)"
        direction TB
        User["User"]:::external
        App["app.py<br/>(UI Router & Orchestrator)"]:::internal
    end

    %% Backend Logic
    subgraph "Backend Logic (utils/)"
        direction TB
        ConfigLoader["config.py<br/>(API Keys & Endpoints)"]:::config
        DotEnv[".env<br/>(Environment Variables)"]:::config
        SharedUtils["utils/abc<br/>(Shared Helpers)"]:::internal
        AirQualityService["AirQualityService<br/>(air_quality.py)"]:::internal
        WeatherService["WeatherService<br/>(weather.py)"]:::internal
        CrimeService["CrimeService<br/>(crime.py)"]:::internal
        TouristService["TouristService<br/>(tourist.py)"]:::internal
        TransportService["TransportService<br/>(transport.py)"]:::internal
        ChatbotService["ChatbotService<br/>(chatbot.py)"]:::internal
    end

    %% External Ecosystem
    subgraph "External APIs & Services"
        direction TB
        OpenWeatherMap["OpenWeatherMap API"]:::external
        GooglePlaces["Google Places API"]:::external
        NewsAPI["News API"]:::external
        GoogleTrends["Google Trends (Pytrends)"]:::external
        GoogleSearch["Google Search Integration"]:::external
    end

    %% Documentation & Dev Setup
    subgraph "Project Docs & Setup"
        direction TB
        README["README.md"]:::docs
        Requirements["requirements.txt"]:::docs
        DevContainer[".devcontainer/devcontainer.json"]:::docs
    end

    %% Data Flow
    User -->|"interacts with"| App
    App -->|"delegates to"| AirQualityService
    App -->|"delegates to"| WeatherService
    App -->|"delegates to"| CrimeService
    App -->|"delegates to"| TouristService
    App -->|"delegates to"| TransportService
    App -->|"delegates to"| ChatbotService

    ConfigLoader -->|provides creds| AirQualityService
    ConfigLoader -->|provides creds| WeatherService
    ConfigLoader -->|provides creds| CrimeService
    ConfigLoader -->|provides creds| TouristService
    ConfigLoader -->|provides creds| TransportService
    ConfigLoader -->|provides creds| ChatbotService

    AirQualityService -->|"HTTP GET → JSON"| OpenWeatherMap
    WeatherService -->|"HTTP GET → JSON"| OpenWeatherMap
    CrimeService -->|"HTTP GET → JSON"| NewsAPI
    TouristService -->|"HTTP GET → JSON"| GooglePlaces
    TransportService -->|"HTTP GET → JSON"| OpenWeatherMap
    ChatbotService -->|"query & parse"| GoogleSearch
    ChatbotService -->|"fetch trends"| GoogleTrends

    OpenWeatherMap -->|returns JSON| AirQualityService
    OpenWeatherMap -->|returns JSON| WeatherService
    NewsAPI -->|returns JSON| CrimeService
    GooglePlaces -->|returns JSON| TouristService
    GoogleSearch -->|returns results| ChatbotService
    GoogleTrends -->|returns data| ChatbotService

    %% Final Rendering
    AirQualityService -->|parsed Data| App
    WeatherService -->|parsed Data| App
    CrimeService -->|parsed Data| App
    TouristService -->|parsed Data| App
    TransportService -->|parsed Data| App
    ChatbotService -->|parsed Data| App

    App -->|"render charts & text"| User

    %% Click Events
    click App "https://github.com/jotthecode/city-pulse/blob/main/app.py"
    click ConfigLoader "https://github.com/jotthecode/city-pulse/blob/main/config.py"
    click DotEnv "https://github.com/jotthecode/city-pulse/blob/main/.env"
    click DevContainer "https://github.com/jotthecode/city-pulse/blob/main/.devcontainer/devcontainer.json"
    click Requirements "https://github.com/jotthecode/city-pulse/blob/main/requirements.txt"
    click SharedUtils "https://github.com/jotthecode/city-pulse/tree/main/utils/abc/"
    click AirQualityService "https://github.com/jotthecode/city-pulse/blob/main/utils/air_quality.py"
    click WeatherService "https://github.com/jotthecode/city-pulse/blob/main/utils/weather.py"
    click CrimeService "https://github.com/jotthecode/city-pulse/blob/main/utils/crime.py"
    click TouristService "https://github.com/jotthecode/city-pulse/blob/main/utils/tourist.py"
    click TransportService "https://github.com/jotthecode/city-pulse/blob/main/utils/transport.py"
    click ChatbotService "https://github.com/jotthecode/city-pulse/blob/main/utils/chatbot.py"
    click README "https://github.com/jotthecode/city-pulse/blob/main/README.md"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#2980B9,color:#1B2631
    classDef external fill:#D5F5E3,stroke:#27AE60,color:#1B2631
    classDef config fill:#FDEBD0,stroke:#D35400,color:#1B2631
    classDef docs fill:#FCF3CF,stroke:#F1C40F,color:#1B2631
```
