Skip to content

02. Architecture

The architecture describes how the platform was built. It contains a description of all components of the solution at different scales and points of view.

This section follows the guidelines of the C4 model (Brown, 2018) to define the architecture of the systems at different levels:

  • Level 1: System Context — At the highest level, the System Context Diagram depicts the system as a single box surrounded by its external entities, such as users, systems, and external dependencies. This diagram provides a broad view of the system and its interactions with the outside world.
  • Level 2: Containers — Container Diagrams focus on the major software systems within the system boundary identified in the System Context Diagram. Containers represent executable software applications, such as web applications, APIs, or databases, that reside within the system.
  • Level 3: Components — Provides a detailed view of the internal elements within each container, including their responsibilities and relationships.

Brown, S. (2018). The C4 Model for Software Architecture. InfoQ. https://www.infoq.com/articles/C4-architecture-model/

Architectural Principles

Principle Description
Modularity Each capability is a separate repository with clear boundaries, enabling independent development, deployment, and evolution.
Separation of Concerns Frontend, API, ORM, and ETLs have distinct responsibilities. Changes in one layer do not cascade to others.
Data Source of Truth The ORM package (aclimate_v3_orm) is the authoritative definition of the data model, schema, relationships, and access patterns.
API-First All data access is mediated through the WebAPI layer. No direct database access from user-facing applications.
Pipeline Isolation ETL processes operate independently and communicate exclusively through the database. This ensures data integrity and enables reprocessing.

Technology Stack

Component Technology Purpose
Frontend TypeScript, React, Next.js End-user web application
WebAPI Python, FastAPI RESTful API services, business logic
ORM Package Python, SQLAlchemy Data model definition, CRUD, migrations
Database PostgreSQL Relational data store
Admin Portal HTML, Python, Flask System configuration and management
ETLs Python Data ingestion, transformation, loading
Keycloak Keycloak Identity and access management (SSO)
GeoServer GeoServer OGC spatial data services (WMS/WFS/WCS)

Component Interaction Flow

External Data Sources (Weather Stations, Satellite Data)
    |
    v
+---------------------------+
|       ETL Layer           |
| (spatial, location, cut)  |
+-----------+---------------+
            |
            v
+---------------------------+
|   PostgreSQL DB           |
| (ORM-managed data store)  |
+-----------+---------------+
            |
            v
+---------------------------+
|   WebAPI (FastAPI)        |
|   + ORM Package           |
+-----------+---------------+
            |
            v
+---------------------------+---------------------------+
|   AClimate Frontend       |   AClimate Admin         |
|   (Next.js)               |   (Flask)                |
+---------------------------+---------------------------+
|   Keycloak (SSO/Auth)     |   GeoServer (Spatial)    |
+---------------------------+---------------------------+