Software Architecture Guide

Quality-focused software development patterns for SAPPHIRE forecast tools.

Project-Specific Conventions

Module Structure

Each module in apps/ follows this pattern:

apps/<module_name>/
├── <module_name>.py      # Entry point script
├── src/                  # Source code
│   ├── __init__.py
│   ├── src.py           # Main module logic (or domain-specific names)
│   └── config.py        # Module configuration (if needed)
├── test/                # Tests (pytest)
├── pyproject.toml       # Dependencies (uv)
├── Dockerfile.py312     # Docker build
└── config.yaml          # Module-specific settings (if needed)

Python Style

• Python version: 3.12 (migrating from 3.11)
• Package manager: uv with pyproject.toml
• Naming: snake_case for functions/variables, PascalCase for classes
• Docstrings: Google style
• Type hints: Required for new code
• Logging: Use logger (from logging module), not print()

Code Patterns

Early returns for readability:

def process_data(data):
    if data is None:
        return None
    if data.empty:
        logger.warning("Empty data received")
        return pd.DataFrame()
    # Main logic here

Environment variables for configuration:

config_path = os.getenv('ieasyforecast_configuration_path')
if config_path is None:
    raise ValueError("ieasyforecast_configuration_path not set")

Error handling with informative messages:

try:
    result = fetch_data(site_id)
except ConnectionError as e:
    logger.error(f"Failed to connect to data source for site {site_id}: {e}")
    raise

General Principles

Library-First Approach

• Check PyPI for existing solutions before writing custom code
• Use established libraries: pandas, numpy, xarray for data; requests for HTTP
• When custom code IS justified:
  • Domain-specific hydrology/forecasting logic
  • Integration with iEasyHydro SDK
  • Performance-critical numerical code

Naming Conventions

• AVOID generic names: utils.py, helpers.py, common.py
• USE domain-specific names: runoff_processor.py, forecast_calculator.py
• Module names should describe their single purpose

Separation of Concerns

• Keep data fetching separate from data processing
• Keep business logic separate from I/O operations
• Each function should do one thing well

Code Quality Guidelines

• Functions under 50 lines when possible
• Files under 300 lines (split if larger)
• Max 3 levels of nesting
• Add comments for non-obvious hydrology/meteorology logic

Docker Patterns

• Base image: mabesa/sapphire-pythonbaseimage:py312
• Use multi-stage builds for smaller images
• Copy only necessary files (not entire repo)
• Set PYTHONUNBUFFERED=1 for log visibility

Testing

• Use pytest with SAPPHIRE_TEST_ENV=True
• Mock external services (iEasyHydro SDK, file I/O)
• Test data processing logic independently from I/O