How cupnoodles7/city-pulse works
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)
– chatbot.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