# actinia-org/actinia-core architecture

> Architecture diagram of the GitHub repository actinia-org/actinia-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/actinia-org/actinia-core
- Repository: https://github.com/actinia-org/actinia-core

## Overview

##### Project Type and Purpose
- Actinia is an open-source backend service (“monolithic” Python application) exposing a REST API for high-performance geographic data processing with GRASS GIS.
- It provides both synchronous HTTP endpoints and asynchronous processing via RQ workers, integrates with cloud object storage (AWS S3, GCS) and external data sources (Landsat/Sentinel archives, BigQuery).

##### File-Structure Analysis
- Top level:
- CLI tools: src/actinia_core/cli (actinia_server, rq_custom_worker, webhook_server, etc.)
- Core logic: src/actinia_core/core/common & core (config, request parsing, logging, interfaces to AWS/GCS/Keycloak, process chains)
- Processing modules: src/actinia_core/processing (ephemeral vs persistent, raster/vector layers, export)
- REST layer: src/actinia_core/rest (endpoint handlers, base classes, API models under models/openapi)
- Tests & QA: tests/, unittests, GitHub workflows, Docker configurations, pre-commit hooks.
- Docker folder contains dedicated images for production, development and testing.
- External-service config: AWS Sentinel interface, GCS, Keycloak for auth, Redis queue for RQ, object storage mounts.

##### Key README Insights
- The service runs in Docker or on bare Python, installs via pip, launches an HTTP server (`actinia_server.py`).
- Exposes Swagger/OpenAPI JSON, asynchronous job submission returns GeoTIFFs in object storage.
- CLI and curl examples show core flow: HTTP POST → queue job → GRASS processing → export to cloud storage → client download.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients
    subgraph "Clients"
        HTTP["HTTP REST Clients"]:::external
        CLI["CLI Tools"]:::internal
        CLI --> CLI1
        CLI1["actinia_server"]:::internal
        CLI --> CLI2
        CLI2["RQ Worker"]:::internal
        CLI --> CLI3
        CLI3["Webhook Server"]:::internal
    end

    %% API Server Layer
    subgraph "API Server" 
        Main["Main Bootstrap"]:::internal
        Health["Health Check"]:::internal
        Factory["App Factory"]:::internal
        Parser["Request Parser"]:::internal
        KCUser["Keycloak Adapter"]:::internal
        NoAuth["No-Auth Adapter"]:::internal
        Controllers["Endpoint Controllers"]:::internal
        Models["API Models"]:::internal
    end

    %% Core Services
    subgraph "Core Services"
        PCM["Process Chain Manager"]:::internal
        PO["Process Object"]:::internal
        PQ["Process Queue"]:::internal
        Config["Config"]:::internal
        APILog["API Logger"]:::internal
        MsgLog["Messages Logger"]:::internal
    end

    %% Storage & External Interfaces
    subgraph "Storage & External Adapters"
        S3Iface["AWS S3 Adapter"]:::internal
        GCSIface["GCS Adapter"]:::internal
        FSIface["Filesystem Adapter"]:::internal
        SentinelIf["AWS Sentinel Interface"]:::internal
        BQIf["BigQuery Interface"]:::internal
        LandsatLib["Landsat Library"]:::internal
        SentinelLib["Sentinel Library"]:::internal
    end

    %% GRASS GIS Integration
    subgraph "GRASS GIS Integration"
        GrassInit["GRASS Init"]:::internal
        GrassMods["GRASS Modules List"]:::internal
        MapMerge["Mapset Merge Utils"]:::internal
    end

    %% Queue & Workers
    subgraph "Queue & Workers"
        Redis["Redis (RQ Broker)"]:::infra
        RQWorker["RQ Custom Worker"]:::infra
    end

    %% Processing Engine
    subgraph "Processing Engine"
        EP["Ephemeral Pipelines"]:::processing
        PP["Persistent Pipelines"]:::processing
        SP["Shared Processing Utils"]:::processing
    end

    %% Data Stores
    subgraph "Data Stores"
        GrassDB["GRASS Database"]:::datasore
        ObjStore["Object Storage"]:::datasore
        KVDB["KVDB / Fluentd"]:::datasore
    end

    %% External Services
    subgraph "External Services"
        AWS["AWS S3"]:::external
        GCS["Google Cloud Storage"]:::external
        BQ["BigQuery"]:::external
        Keycloak["Keycloak"]:::external
    end

    %% Docker
    subgraph "Docker Compose"
        Compose["Docker Compose"]:::infra
    end

    %% Connections
    HTTP -->|HTTP/JSON| Main
    CLI1 --> Main
    Main --> Parser
    Main --> Factory
    Parser --> KCUser
    Parser --> NoAuth
    Factory --> Controllers
    Controllers --> Models
    Controllers --> PCM
    Controllers --> PQ
    Controllers -->|Sync| GrassInit
    Controllers -->|Async| Redis
    Redis --> RQWorker
    RQWorker --> PQ
    PQ --> EP
    PQ --> PP
    EP --> SP
    PP --> SP
    SP --> GrassInit
    GrassInit --> GrassMods
    GrassInit --> MapMerge
    EP --> SentinelIf
    EP --> BQIf
    EP --> LandsatLib
    EP --> SentinelLib
    EP --> GrassDB
    PP --> GrassDB
    EP --> ObjStore
    PP --> ObjStore
    ObjStore -->|GeoTIFF| AWS
    ObjStore -->|GeoTIFF| GCS
    Controllers --> KVDB
    KVDB -->|logs| KVDB
    KVDB -->|forward| KVDB
    Compose --> Main
    Compose --> Redis
    Compose --> ObjStore

    %% Click Events
    click CLI1 "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/cli/actinia_server.py"
    click CLI2 "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/cli/rq_custom_worker.py"
    click CLI3 "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/cli/webhook_server.py"
    click Main "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/main.py"
    click Health "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/health_check.py"
    click Factory "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/app.py"
    click Parser "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/request_parser.py"
    click KCUser "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/keycloak_user.py"
    click NoAuth "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/user_noauth.py"
    click Controllers "https://github.com/actinia-org/actinia-core/tree/main/src/actinia_core/rest/"
    click Models "https://github.com/actinia-org/actinia-core/tree/main/src/actinia_core/models/openapi/"
    click PCM "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/process_chain.py"
    click PO "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/process_object.py"
    click PQ "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/process_queue.py"
    click Config "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/config.py"
    click APILog "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/api_logger.py"
    click MsgLog "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/messages_logger.py"
    click S3Iface "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/storage_interface_aws_s3.py"
    click GCSIface "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/storage_interface_gcs.py"
    click FSIface "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/storage_interface_filesystem.py"
    click SentinelIf "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/aws_sentinel_interface.py"
    click BQIf "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/google_satellite_bigquery_interface.py"
    click LandsatLib "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/landsat_processing_library.py"
    click SentinelLib "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/sentinel_processing_library.py"
    click GrassInit "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/grass_init.py"
    click GrassMods "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/grass_modules_list.py"
    click MapMerge "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/mapset_merge_utils.py"
    click EP "https://github.com/actinia-org/actinia-core/tree/main/src/actinia_core/processing/actinia_processing/ephemeral/"
    click PP "https://github.com/actinia-org/actinia-core/tree/main/src/actinia_core/processing/actinia_processing/persistent/"
    click SP "https://github.com/actinia-org/actinia-core/tree/main/src/actinia_core/processing/common/"
    click KVDB "https://github.com/actinia-org/actinia-core/blob/main/src/actinia_core/core/common/kvdb_base.py"
    click Compose "https://github.com/actinia-org/actinia-core/blob/main/docker/docker-compose.yml"

    %% Styles
    classDef internal fill:#c2f0c2,stroke:#2d702d
    classDef processing fill:#ffd699,stroke:#b58031
    classDef external fill:#c2d9f0,stroke:#1b4f8a
    classDef infra fill:#e0e0e0,stroke:#707070
    classDef datasore fill:#ffeecc,stroke:#aa6600
```
