How jotthecode/city-pulse works
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.)