Level 3: Components¶

The C4 Model Level 3 provides a detailed view of the internal elements within each container, including their responsibilities and relationships.

Diagram¶

Architecture Level 3 - Components AClimate

Component	Responsibility
Auth Middleware	Validates JWT tokens from Keycloak for every request. Rejects unauthenticated or unauthorized access.
Geographic Controller	Handles endpoints for countries, admin level 1, admin level 2, and locations. Maps to MngCountry, MngAdmin1, MngAdmin2, MngLocation ORM models.
Climate Controller	Exposes historical daily/monthly data, climatology normals, and derived indicators. Supports filtering by date, location, and variable.
Forecast Controller	Serves 10-day, sub-seasonal, and seasonal forecasts. Includes analogue year data.
Agronomic Controller	CRUD operations for crops, cultivars, soils, setups, and seasons.
Recommendation Controller	Generates agronomic recommendations based on climate data and crop models.
Error Handler	Standardizes error responses with consistent format and HTTP status codes.

#	Entity	Table	Domain
1	MngCountry	mng_country	Management
2	MngAdmin1	mng_admin_1	Management
3	MngAdmin2	mng_admin_2	Management
4	MngLocation	mng_location	Management
5	MngCrop	mng_crop	Management
6	MngCultivar	mng_cultivar	Management
7	MngSoil	mng_soil	Management
8	MngSeason	mng_season	Management
9	MngSetup	mng_setup	Management
10	MngSource	mng_source	Management
11	MngDataSource	mng_data_source	Management
12	MngClimateMeasure	mng_climate_measure	Management
13	MngIndicator	mng_indicator	Management
14	MngIndicatorCategory	mng_indicator_category	Management
15	MngIndicatorsFeatures	mng_indicators_features	Management
16	MngPhenologicalStage	mng_phenological_stage	Management
17	MngStress	mng_stress	Management
18	MngConfigurationFile	mng_configuration_file	Management
19	MngCountryIndicator	mng_country_indicator	Management
20	MngCountryClimateMeasure	mng_country_climate_measure	Management
21	Forecast	forecast	Forecast
22	ForecastAnalogue	forecast_analogue	Forecast
23	ClimateHistoricalDaily	climate_historical_daily	Climate
24	ClimateHistoricalMonthly	climate_historical_monthly	Climate
25	ClimateHistoricalClimatology	climate_historical_climatology	Climate
26	ClimateHistoricalIndicator	climate_historical_indicator	Climate
27	HistoricalAgroclimaticIndicator	historical_agroclimatic_indicator	Agroclimatic
28	PhenologicalStageStress	phenological_stage_stress	Phenology
29	User	user	Security
30	Role	role	Security
31	UserAccess	user_access	Security

Component	Count	Responsibility
Schemas	31 files	Pydantic models for API request/response serialization
Services	31 files	Business logic layer with CRUD operations
Validations	31 files	Data integrity rules applied before persistence
Enums	7 files	app, indicator_feature_type, indicators_type, module, period, source_type, stress_category
Migrations	Alembic	Version-controlled schema evolution scripts

Component	Description
Country Management	CRUD for countries. Configure ISO2 codes, names, enable/disable.
Admin Level 1 Management	Manage first-level divisions (departments, states, provinces).
Admin Level 2 Management	Manage second-level divisions (municipalities, districts).
Location Management	Manage points of interest (weather stations, monitoring points). Configure metadata and parameters.
Crop Management	Define crop types with names and codes.
Cultivar Management	Manage cultivar varieties per country and crop.
Soil Management	Configure soil types per country.
Season Management	Define growing seasons for different regions and crops.
Setup Management	Configure crop setup parameters and simulation conditions.
Data Import	Bulk import interfaces for historical climate data.
User Management	User CRUD, role assignment, and access control via Keycloak integration.
Configuration Management	Climate parameters, data source configuration, ETL monitoring.

Component	Description
Realm	Independent security domain for AClimate v3.
Client	Each application (Frontend, Admin) registers as a client with specific configurations.
Role	Permission levels: admin (full access), viewer (read-only), editor (modify data).
User	User accounts with assigned roles, encrypted credentials, and profile information.
Token	JWT access token + refresh token flow for secure authentication.
Session	Active user session tracking and management with audit events.

Component	Description
WMS	Web Map Service - renders map images (PNG, JPEG) of climate layers.
WFS	Web Feature Service - serves vector features (GeoJSON, GML) of boundaries and stations.
WCS	Web Coverage Service - serves raster/coverage data for climate variables.
GeoWebCache	Tile caching for improved map rendering performance.
SLD	Styled Layer Descriptor for map layer customization and styling.

Component	Description
Connector ERA5	Downloads ERA5 climate data (global grid, multiple variables). Transforms to local format.
Connector CHIRPS	Downloads CHIRPS precipitation data. Converts to raster format.
Setup Module	Manages credentials, API keys, and download parameters for spatial data sources.
Calculate Monthly Data	Aggregates daily data to monthly temporal resolution.
Calculate Climatology	Computes historical averages for temperature, precipitation, solar radiation.
Calculate Indicators	Derives climate indicators: dry/wet spell indices, heatwave indices, water balance indices.
Validation Package	Checks data integrity, imputes missing values from climatology.
Main Script	Coordinates all modules, manages execution flow, writes results to database.

Component	Description
Connector	Accesses station data from data sources. Downloads daily observations.
Setup Module	Manages connections to data sources (IDEAM, providers).
Calculate Monthly Data	Aggregates daily station data to monthly.
Calculate Climatology	Computes station-level climatological normals.
Calculate Indicators	Derives location-based climate indicators.
Validation Package	Quality control, missing value imputation, temporal consistency checks.
Main Script	Coordinates execution, manages flow, writes to database.