# cupnoodles7/city-pulse architecture

> Architecture diagram of the GitHub repository cupnoodles7/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/cupnoodles7/city-pulse
- Repository: https://github.com/cupnoodles7/city-pulse

## Overview

##### Project Type and Purpose
- City Pulse is a full-stack, single-page dashboard application built with Streamlit (Python).
- Its purpose is to present real-time city insights—weather, air quality, crime news, tourist spots, Google Trends charts, and AI chatbot answers—by aggregating multiple external APIs.

##### File Structure
Top-level layout:
- .devcontainer/ – development environment config (VS Code DevContainer).
- .env – environment variables (API keys, secrets).
- config.py – centralized config loader (reads .env).
- app.py – Streamlit entrypoint (defines UI, layout, page routing).
- requirements.txt – Python dependencies.
- utils/ – business logic modules, one per data domain:
– weather.py, air_quality.py
– crime.py, tourist.py, transport.py
– google_trends (via pytrends)
– chatbot.py (custom Google Search wrapper)

##### Key Insights from README
- Frontend: Streamlit UI components and custom HTML/CSS.
- Backend: Python “service” layer in utils; no persistent database (stateless).
- External APIs: OpenWeatherMap, Google Places, News API, Pytrends, Google Search.
- Data processing: pandas for tabulation/aggregation.

a. Main Components
1. Streamlit Web UI (app.py)
2. Service Layer (utils/*.py modules)
3. Configuration (config.py + .env)
4. External APIs:
– OpenWeatherMap (weather + AQI)
– Google Places (tourist)
– News API (crime)
– Pytrends (Google Trends)
– Google Search (chatbot)
5. Developers’ Environment (DevContainer)

b. Relationships & Data Flow
- User → Streamlit UI → triggers function
- UI calls Service Layer (e.g., get_weather(city))
- Service Layer reads config (API keys), makes HTTP requests to External API
- Response → pandas processing → returns data object (charts, tables) → UI renders
- For Chatbot: UI sends user query → chatbot.py → Google Search → NLP/format → UI

c. Architectural Patterns & Principles
- Layered Architecture: UI layer separate from service layer.
- Single responsibility: each utils module handles one domain.
- Configuration abstraction: config.py centralizes secrets.
- Stateless design: no database or persistent store.

d. Key Technologies & Libraries
- Streamlit (web UI)
- Python requests (HTTP client)
- Pandas (data manipulation)
- Pytrends (Google Trends)
- python-dotenv (config)
- Docker/DevContainer (development environment)

##### Detailed Component Breakdown (
1. Streamlit UI (app.py)
– Page controls: sidebar, main charts, tables
2. Config Loader (config.py + .env)
– Exposes API_KEYs to service modules
3. Service Modules (utils/)
– weather.py → OpenWeatherMap
– air_quality.py → OpenWeatherMap AQI endpoint
– crime.py → News API
– tourist.py → Google Places API
– transport.py → (if any transport API)
– chat­bot.py → Google Search integration
– google_trends.py → Pytrends
4. External API Endpoints
– Weather & AQI (OpenWeatherMap)
– Google Places
– News API
– Google Trends (Pytrends client)
– Google Search

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["End User"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Streamlit_UI["Streamlit Web UI\n(app.py)"]:::frontend
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        direction TB
        Config["Config Loader\n(config.py)"]:::config
        Env["Environment Variables\n(.env)"]:::config
    end

    %% Development Environment
    subgraph "Development Environment"
        direction TB
        DevContainer["VSCode DevContainer\n(.devcontainer/devcontainer.json)"]:::dev
    end

    %% Service Layer
    subgraph "Service Layer (utils)"
        direction TB
        Init["Package Init\n(utils/__init__.py)"]:::service
        Weather["Weather Service\n(utils/weather.py)"]:::service
        AirQuality["Air Quality Service\n(utils/air_quality.py)"]:::service
        Crime["Crime News Service\n(utils/crime.py)"]:::service
        Tourist["Tourist Spots Service\n(utils/tourist.py)"]:::service
        Transport["Transport Service\n(utils/transport.py)"]:::service
        Chatbot["Chatbot Service\n(utils/chatbot.py)"]:::service
    end

    %% External APIs
    subgraph "External APIs"
        direction TB
        OW_Weather["OpenWeatherMap\n(Weather)"]:::external
        OW_AQI["OpenWeatherMap\n(AQI)"]:::external
        GooglePlaces["Google Places API"]:::external
        NewsAPI["News API"]:::external
        Pytrends["Google Trends\n(Pytrends)"]:::external
        GoogleSearch["Google Search"]:::external
    end

    %% Connections
    User -->|Uses| Streamlit_UI
    Streamlit_UI -->|calls| Weather
    Streamlit_UI -->|calls| AirQuality
    Streamlit_UI -->|calls| Crime
    Streamlit_UI -->|calls| Tourist
    Streamlit_UI -->|calls| Transport
    Streamlit_UI -->|calls| Chatbot

    %% Service to Config
    Weather -->|reads API_KEY| Config
    AirQuality -->|reads API_KEY| Config
    Crime -->|reads API_KEY| Config
    Tourist -->|reads API_KEY| Config
    Transport -->|reads API_KEY| Config
    Chatbot -->|reads API_KEY| Config

    Env --> Config

    %% Service to External
    Weather -->|HTTP Request| OW_Weather
    OW_Weather -->|Response| Weather

    AirQuality -->|HTTP Request| OW_AQI
    OW_AQI -->|Response| AirQuality

    Crime -->|HTTP Request| NewsAPI
    NewsAPI -->|Response| Crime

    Tourist -->|HTTP Request| GooglePlaces
    GooglePlaces -->|Response| Tourist

    Transport -->|HTTP Request| OW_Weather
    OW_Weather -->|Response| Transport

    Chatbot -->|HTTP Request| GoogleSearch
    GoogleSearch -->|Response| Chatbot

    %% Data back to UI
    Weather -->|data| Streamlit_UI
    AirQuality -->|data| Streamlit_UI
    Crime -->|data| Streamlit_UI
    Tourist -->|data| Streamlit_UI
    Transport -->|data| Streamlit_UI
    Chatbot -->|data| Streamlit_UI

    %% DevContainer to everything
    DevContainer -->|hosts| Streamlit_UI
    DevContainer -->|hosts| Config
    DevContainer -->|hosts| Init

    %% Click Events
    click Streamlit_UI "https://github.com/cupnoodles7/city-pulse/blob/main/app.py"
    click Config "https://github.com/cupnoodles7/city-pulse/blob/main/config.py"
    click Env "https://github.com/cupnoodles7/city-pulse/blob/main/.env"
    click DevContainer "https://github.com/cupnoodles7/city-pulse/blob/main/.devcontainer/devcontainer.json"
    click Weather "https://github.com/cupnoodles7/city-pulse/blob/main/utils/weather.py"
    click AirQuality "https://github.com/cupnoodles7/city-pulse/blob/main/utils/air_quality.py"
    click Crime "https://github.com/cupnoodles7/city-pulse/blob/main/utils/crime.py"
    click Tourist "https://github.com/cupnoodles7/city-pulse/blob/main/utils/tourist.py"
    click Transport "https://github.com/cupnoodles7/city-pulse/blob/main/utils/transport.py"
    click Chatbot "https://github.com/cupnoodles7/city-pulse/blob/main/utils/chatbot.py"
    click Init "https://github.com/cupnoodles7/city-pulse/blob/main/utils/__init__.py"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px
    classDef service fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#ffa500,stroke:#000,stroke-width:1px
    classDef config fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef dev fill:#eeeeee,stroke:#000,stroke-width:1px
    classDef user fill:#ffffff,stroke:#000,stroke-width:1px;font-weight:bold
```
