A production-style weather data service with intelligent caching, query history, and dual interfaces (REST API + CLI). Built to demonstrate clean architecture, async Python, and real-world backend patterns.

This is a portfolio project designed to demonstrate:

• Clean Architecture (Ports & Adapters)
• Async Python across the entire stack
• Separation of concerns (API / domain / infrastructure)
• External API integration with caching, retry logic, and fallback strategies
• Professional engineering practices (ADRs, testing strategy, documentation)

git clone https://github.com/lridalc/weather-analytics-dashboard
cd weather-analytics-dashboard

# Install dependencies
make install-dev

# Configure environment
cp .env.example .env

# Run API
make dev

# Test endpoints
curl http://localhost:8000/health
curl "http://localhost:8000/weather/current?city=London"

# CLI usage
make cli now London

This project follows a vertical-slice, test-driven development approach, where each milestone delivers a fully working feature across all layers.

• Project scaffolding
• Documentation structure (README, ADRs, scope)
• Smoke tests (API + CLI)
• CI/CD pipeline setup and automation
• Settings & configuration system
• Base FastAPI application bootstrap

• /health endpoint implementation
• Health check tests
• Minimal API wiring validation

• Domain models for weather
• Use case: get current weather
• Geocoding service (shared infrastructure)
• Open-Meteo adapter integration
• /weather/current endpoint with error mapping
• CLI: weather now <city>
• Full integration tests

• Forecast domain model
• Forecast use case implementation
• Open-Meteo adapter extension for forecasts
• /weather/forecast endpoint with error mapping
• CLI: weather forecast <city> --days N

• History domain contracts (port + models)
• SQLite repository with aiosqlite
• FIFO eviction (max 10 entries per city)
• History retrieval service
• Automatic query persistence on current
• /weather/history endpoint with error mapping
• CLI: weather history <city>

• HTTP client with exponential backoff (tenacity)
• Global rate limiting (quota protection)
• Migration of OpenMeteoAtapter to retry-enabled client
• Retry only on transient errors (5xx, timeouts)

• Weather cache decorator (5 min TTL)
• FIFO eviction for weather cache
• Geocoding cache (7 days TTL, internal to service)
• Cache hit/miss integration tests
• Dependency wiring for cached provider

• All endpoints complete
• CLI feature parity with API
• Full async execution (no blocking I/O)
• Clean Architecture enforced across layers
• High test coverage achieved
• Production-ready documentation

✔ Automatic OpenAPI docs at /docs

weather now Madrid
weather forecast Paris --days 5
weather history Tokyo

Same business logic as API → different interface.

Two-layer cache system:

✔ Reduces API calls significantly ✔ Improves response time (<200ms cached) ✔ FIFO eviction prevents memory leaks

Architectural note: These two caches operate at different layers:

• Weather cache wraps the domain port (system-wide)
• Geocoding cache is internal to the shared geocoding service (infrastructure detail)

From a user perspective, both contribute to performance optimization.

• Automatic retry with exponential backoff on transient external API failures
• Global rate limiting (55 req/min) to protect the external API quota
• Graceful degradation when the provider is unavailable

• SQLite persistence
• Last 10 queries per location
• FIFO eviction
• Survives restarts

• FastAPI (ASGI)
• HTTPX (non-blocking HTTP)
• SQLAlchemy async + aiosqlite

✔ No blocking I/O ✔ Efficient concurrent handling

This project follows Clean Architecture + Ports & Adapters:

Presentation (API / CLI)
        ↓
Application (Use Cases)
        ↓
Domain (Business Logic)
        ↑
Infrastructure (DB, Cache, External APIs)

• Provider Pattern (Port + Adapter) → external weather services abstraction
• Repository Pattern → database abstraction
• Decorator Pattern → caching layer
• Service Layer → use case orchestration
• Dependency Injection → testability

📚 Documentation:

• docs/architecture.md
• docs/decisions.md

Weather data retrieval is provider-driven:

• The domain interacts with a single abstraction: WeatherProvider
• Each provider implementation decides how to resolve a location

1. Resolve location → coordinates (via shared geocoding service)
2. Fetch weather data using coordinates

This logic is fully encapsulated inside the provider adapter, keeping the domain and application layers independent of provider-specific requirements.

✔ No geocoding concepts leak into the domain ✔ Shared geocoding service prevents logic duplication across providers ✔ Easy to swap providers without changing business logic

The current structure is the foundational layer. The system will evolve incrementally following the design defined in ADR-023.

.
├── docs/                                  # Architecture, ADRs, and development planning
│   ├── architecture.md
│   ├── decisions.md
│   ├── development-plan.md
│   └── project-scope.md
│
├── src/weather_analytics_dashboard/
│   ├── application/                       # Use cases (business workflows)
│   │   └── services/
│   │       └── get_current_weather.py
│   ├── config/                            # Configuration, settings, constants, and exceptions
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   ├── logging.py
│   │   └── settings.py
│   ├── domain/                            # Core business logic and models
│   │   ├── exceptions.py
│   │   ├── models.py
│   │   └── ports.py
│   ├── infrastructure/                    # External systems (DB, APIs, cache)
│   ├── presentation/                      # Interfaces (API + CLI)
│   │   ├── api/
│   │   │   ├── app.py
│   │   │   ├── dependencies.py
│   │   │   ├── routes/
│   │   │   │   └── health.py
│   │   │   └── schemas/
│   │   │       └── health.py
│   │   └── cli/
│   │       └── main.py
│   ├── bootstrap.py                       # Dependency injection and app initialization
│   └── main.py                            # Application entry point
│
├── tests/
│   ├── integration/                       # Integration tests (API, DB)
│   │   ├── bootstrap/
│   │   ├── config/
│   │   ├── presentation/
│   │   │   ├── api/
│   │   │   └── cli/
│   │   └── test_00_smoke.py
│   ├── unit/                              # Unit tests (domain & services)
│   │   └── config/
│   │       └── test_settings.py
│   └── conftest.py                        # Pytest fixtures and configuration
│
├── .github/                               # CI/CD workflows, actions, and PR templates
│   ├── actions/
│   ├── workflows/
│   └── pull_request_template.md
│
├── Makefile                               # Development commands
├── pyproject.toml                         # Project configuration and dependencies
└── README.md

GET /weather/current?city=London

{
  "city": "London",
  "temperature": 18.5,
  "timestamp": "2026-04-08T12:00:00Z"
}

GET /weather/forecast?city=London&days=3

{
  "city": "London",
  "forecast": [
    {
      "date": "2026-04-09",
      "min_temp": 12.1,
      "max_temp": 19.3,
      "avg_temp": 15.7
    }
  ]
}

GET /weather/history?city=London

{
  "city": "London",
  "history": [
    {
      "timestamp": "2026-04-08T12:00:00Z",
      "temperature": 18.5
    }
  ]
}

{
  "error": {
    "code": "CITY_NOT_FOUND",
    "message": "Location could not be resolved"
  }
}

make test

This project uses a Makefile to standardize development workflows and ensure consistency across environments.

make all          # Install everything necessary for development (install-dev + pre-commit)
make install      # Install production dependencies
make install-dev  # Install all dependencies including development tools

make dev  # Run API with hot reload (development)
make run  # Run API without reload (production-like)
make cli  # Run CLI tool

make test              # Run all tests
make test-smoke        # Run smoke tests
make test-bootstrap    # Run bootstrap tests
make test-unit         # Run unit tests
make test-integration  # Run integration tests
make test-cov          # Run tests with coverage report

All tests are run with verbose output.

make lint         # Run ruff linter
make format       # Auto-format code
make format-diff  # Show formatting differences without applying changes
make format-check # Check formatting without modifying files
make type-check   # Run mypy static type checking

make pre-commit                    # Install pre-commit hooks
make pre-commit-force              # Force reinstall pre-commit hooks
make pre-commit-all                # Run all hooks on all files
make pre-commit-run HOOK=ruff      # Run specific hook
make pre-commit-update             # Update hooks to latest versions
make pre-commit-uninstall          # Uninstall pre-commit hooks

make check

Runs all quality checks:

• Linting (ruff)
• Formatting validation (ruff)
• Tests (pytest)
• Type checking (mypy)

make clean

Removes cache files and temporary artifacts:

• __pycache__
• .pyc
• .mypy_cache
• .pytest_cache
• .ruff_cache

make version                      # Show current version
make release                      # Show release process steps
make release VERSION=0.2.0        # Execute release (creates tag, pushes, syncs branches)

make ci                           # Run complete CI pipeline locally (same as GitHub Actions)

make help

Displays all available commands (default).

gunicorn weather_analytics_dashboard.main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker

• Redis cache
• Docker support
• Cloud deployment (Railway / Render)

• Metrics endpoint (Prometheus)
• Redis cache
• PostgreSQL support
• Docker

MIT License

lridalc - https://github.com/lridalc

Project Link - https://github.com/lridalc/weather-analytics-dashboard

This project is intentionally designed to reflect real-world backend engineering, including:

• Clear architectural boundaries
• Explicit trade-offs (documented via ADRs)
• Provider abstraction without leaking infrastructure details
• Resilience patterns (retry with exponential backoff)
• Async-first design
• Testable, modular components

This project was built to practice designing a production-ready backend system from scratch, focusing on maintainability, scalability, and real-world trade-offs.

It is not just a weather API wrapper—it is a system design exercise implemented in code.