📊 Economic Monitor

A production-ready economic dashboard that aggregates real-time US and global economic indicators from multiple authoritative data sources. Built with Streamlit and powered by FRED and World Bank APIs.

---

🚀 Features

📈 Multi-Source Data Integration

• FRED API: 5+ US economic indicators updated hourly
• World Bank API: 6 global economic metrics across 10+ countries
• Smart Caching: 1-hour cache for FRED, 24-hour cache for World Bank to minimize API calls

🎨 Four Interactive Dashboard Tabs

1. Overview - Current Economic Snapshot

   • KPI cards with real-time values
   • Trend indicators (↑/↓ with color coding)
   • Sparkline charts for quick trend visualization
   • Key metrics: CPI, Unemployment Rate, Fed Funds Rate, Treasury Yields

2. Economic Trends - Historical Time Series

   • Interactive 5-year historical charts
   • Multiple indicator visualization
   • CPI and unemployment rate trends
   • Hover-based data inspection

3. Comparison - Year-over-Year Analysis

   • Side-by-side metric comparison
   • Heatmap visualization of YoY changes
   • Percentage change tracking
   • Statistical summaries

4. Country Comparison - Global Economic Data

   • Multi-country selector
   • Metric selector (GDP, Inflation, Debt-to-GDP, etc.)
   • Comparison charts and heatmaps
   • 10+ countries supported

🎯 Production-Ready Code

• ✅ 93 comprehensive test cases (100% passing)
• ✅ Type-safe Python with full type hints
• ✅ Clean 4-layer architecture (Config → Services → Visualization → Controllers)
• ✅ Modular, testable functions
• ✅ Professional dark finance theme

---

🏗️ Architecture

Layered Design Pattern

┌─────────────────────────────────┐
│  Controllers (main.py)          │  Streamlit UI Layer
├─────────────────────────────────┤
│  Visualization (charts, cards)  │  Rendered Components
├─────────────────────────────────┤
│  Services (FRED, World Bank)    │  Data Processing & APIs
├─────────────────────────────────┤
│  Configuration (settings)       │  Constants & Config
└─────────────────────────────────┘

Project Structure

economy_monitor/
├── app/
│   └── main.py                 # Streamlit entry point
├── src/
│   ├── config/
│   │   └── settings.py         # API keys, indicators, caching config
│   ├── services/
│   │   ├── fred_service.py     # FRED API client
│   │   ├── economic_service.py # Data processing (CPI, unemployment)
│   │   └── world_bank_service.py # World Bank API client
│   ├── visualization/
│   │   ├── theme.py            # Dark finance color palette
│   │   ├── charts.py           # Plotly chart generators
│   │   ├── cards.py            # Streamlit card components
│   │   └── country_comparison.py # Multi-country visualizations
│   ├── controllers/
│   │   └── main.py             # Dashboard orchestration
│   └── models/
│       └── types.py            # TypedDict definitions
├── tests/
│   ├── test_fred_service.py
│   ├── test_economic_service.py
│   ├── test_visualization.py
│   ├── test_cards.py
│   ├── test_world_bank_service.py
│   └── test_country_comparison.py
├── specs/                      # Product specifications
├── tasks/                      # Development roadmap
├── requirements.txt
└── .gitignore

---

🛠️ Tech Stack

Layer	Technology	Purpose
Frontend	Streamlit	Interactive web dashboard
Visualization	Plotly	Interactive charts with dark theme
Data Processing	Pandas	Vectorized operations, aggregations
APIs	fredapi, requests	Data fetching from FRED & World Bank
Testing	pytest	Comprehensive test suite
Language	Python 3.11	Type-safe with full type hints

---

📦 Installation

Prerequisites

• Python 3.11+
• pip or conda

Setup

1. Clone the repository

   git clone https://github.com/yourusername/economy_monitor.git
   cd economy_monitor

2. Create a virtual environment

   python -m venv .venv
   .venv\Scripts\activate  # On Windows
   source .venv/bin/activate  # On macOS/Linux

3. Install dependencies

   pip install -r requirements.txt

4. Configure API Keys

   Create a .env file in the project root:

   FRED_API_KEY=your_fred_api_key_here
   

   Get your free FRED API key: https://fred.stlouisfed.org/docs/api/

5. Run the dashboard

   streamlit run app/main.py

   The dashboard will open at http://localhost:8501

---

🔌 API Integrations

FRED (Federal Reserve Economic Data)

• Provider: St. Louis Federal Reserve
• Update Frequency: Daily
• Cache Duration: 1 hour
• Indicators:
  • CPI (Consumer Price Index)
  • Unemployment Rate
  • Federal Funds Rate
  • 10-Year Treasury Yield
  • 2-Year Treasury Yield

World Bank

• Provider: World Bank Open Data

• Update Frequency: Annual

• Cache Duration: 24 hours

• Indicators:

  • GDP (current USD)
  • GDP per capita
  • Inflation Rate
  • Debt-to-GDP Ratio
  • Unemployment Rate
  • Population

• Countries Supported: US, China, Japan, Germany, UK, India, France, Italy, Canada, South Korea

---

📊 Dashboard Features

KPI Cards

• Real-time indicator values
• Trend direction indicators (↑ Green, ↓ Red)
• Percentage change from previous period
• Sparkline mini-charts for visual trends

Interactive Charts

• Time series with hover tooltips
• Year-over-year comparison heatmaps
• Multi-metric comparison bar charts
• Country comparison visualizations

Dark Finance Theme

• Professional dark background (#0f1419)
• Cyan (#00d4ff) for rises/positive trends
• Green (#00ff88) for gains
• Red (#ff3860) for declines

---

🧪 Testing

The project includes 93 comprehensive test cases across 6 test modules.

Run All Tests

pytest tests/ -v

Run Specific Test Module

pytest tests/test_fred_service.py -v

Test Coverage

• ✅ FRED Service (4 tests) - API client validation
• ✅ Economic Service (6+ tests) - Data processing logic
• ✅ Visualization (20+ tests) - Chart rendering
• ✅ Cards (25 tests) - Card component rendering
• ✅ World Bank Service (18 tests) - Global data fetching
• ✅ Country Comparison (24 tests) - Multi-country visualizations

Test Status: 93/93 passing (100%)

---

🚀 Usage Examples

View Current US Economic Indicators

1. Open the dashboard
2. Navigate to Overview tab
3. See current CPI, Unemployment, Fed Rate, and Treasury Yields with trend indicators

Analyze Historical Trends

1. Go to Economic Trends tab
2. Interactive 5-year time series charts
3. Hover over data points for exact values

Compare Economic Metrics

1. Visit Comparison tab
2. View year-over-year changes side-by-side
3. Identify economic patterns and trends

Monitor Global Economics

1. Click Country Comparison tab
2. Select countries from dropdown
3. Choose economic metric to compare
4. View country-level comparison charts

---

💻 Development

Adding a New Indicator

1. Add to settings.py

   'NEW_INDICATOR': 'FRED_SERIES_ID'

2. Create service function

   def fetch_new_indicator() -> float:
       return fetch_indicator('NEW_INDICATOR')

3. Add visualization in charts.py

4. Write tests in tests/test_your_module.py

5. Integrate in main.py dashboard

Code Standards

• Type hints required for all functions
• Minimum 80% test coverage
• Follow PEP 8 style guide
• Docstrings for all public functions

---

📈 Data Sources

• FRED: https://fred.stlouisfed.org/
• World Bank: https://data.worldbank.org/
• Specifications: See /specs directory
• Development Roadmap: See /tasks directory

---

📝 Specifications

Complete product and development specifications available in /specs:

• product-spec.md - Feature requirements
• ui-spec.md - UI/UX design
• data-sources.md - API integration details
• architecture.md - System design
• development-rules.md - Coding standards

---

🤝 Contributing

This is a specification-driven project. Before contributing:

1. Review the roadmap in /tasks/roadmap.md
2. Check the development rules in /specs/development-rules.md
3. Write tests for new features
4. Ensure all tests pass before submitting

---

📄 License

MIT License - See LICENSE file for details

---

🐛 Troubleshooting

Dashboard won't start

# Check Python version
python --version  # Should be 3.11+

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

API errors

• Verify .env file has valid FRED_API_KEY
• Check internet connection
• Ensure API keys haven't expired

Tests failing

# Clear pytest cache
pytest --cache-clear tests/ -v

---

📞 Support

For issues or questions:

1. Check the specifications in /specs
2. Review the development roadmap in /tasks
3. Consult test cases for usage examples
4. Check project documentation files

---

✨ Status

• ✅ All 6 development tasks completed
• ✅ 93 test cases (100% passing)
• ✅ Production-ready code
• ✅ Dashboard operational
• ✅ Full API integration

Last Updated: March 2026