# isc-konstanz/lories architecture

> Architecture diagram of the GitHub repository isc-konstanz/lories, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/isc-konstanz/lories
- Repository: https://github.com/isc-konstanz/lories

## Overview

1. **What this repository is**
   - `lories` is a Python package for local resource integration and execution systems. Its architecture is centered on collecting data from physical/remote resources, transforming it, and optionally presenting or exporting it through a higher-level application layer.

2. **Overall layering**
   - The codebase is organized into a reusable runtime core, a data-processing layer, a connector layer for external systems, domain-specific components, and an `application/` layer for user-facing pages/views.
   - This creates a clear separation between infrastructure access, data flow, and presentation.

3. **Bootstrap and configuration**
   - Startup is driven by package entrypoints (`lories/__main__.py`) and configuration files under `conf/` plus the core configuration modules.
   - The core config subsystem handles loading settings, directories, TOML-based config, logging defaults, and application-wide constants.

4. **Core runtime and registry model**
   - The `core/` and `_core/` packages provide the framework primitives: application lifecycle, activators, contexts, resources, registries/registrators, and typed abstractions for components and data.
   - This is the internal backbone that other layers depend on for discovery, wiring, and lifecycle management.

5. **Connectors: the external-system boundary**
   - `lories/connectors/` is the integration layer for talking to real-world systems and protocols.
   - It includes adapters for CSV, SQL, InfluxDB, MQTT, OPC UA, Modbus, serial/I2C/SDI12, cameras/OpenCV, RevPi, math/virtual sources, and an entsoe connector, making connectors the main ingress/egress boundary to hardware, files, and services.

6. **Data pipeline**
   - `lories/data/` turns raw connector output into managed streams.
   - Key subsystems here are channels, converters, processors, listeners, filters, databases, retention/replication, validation, and task orchestration; this is where values are normalized, enriched, persisted, and distributed.

7. **Channel-to-connector flow**
   - The `data/channels` modules bridge connectors into the processing pipeline, while converters and processors reshape raw readings into usable domain values.
   - The presence of listeners and retention/replication suggests the data layer supports both live reactions and longer-lived storage/duplication of processed results.

8. **Domain components**
   - `lories/components/` contains higher-level business/domain modules rather than low-level plumbing.
   - The bundled weather and tariff domains show a pattern of provider-based integration: e.g. DWD/BrightSky for weather and ENTSOE/static providers for tariff data, built on top of the connector/data foundation.

9. **Application and UI layer**
   - `lories/application/` is a separate presentation boundary with settings, an interface, login/authentication, and page/component/layout modules.
   - The page registry and reusable view components indicate a structured UI composition layer that consumes the underlying components/data rather than directly talking to external systems.

10. **Import/export and analysis utilities**
   - `lories/io/` provides file/output-oriented utilities such as CSV, Excel, and plotting, which are likely used for reporting, export, and visualization.
   - `simulation/` provides durations, progress, and result containers, suggesting offline or synthetic execution flows alongside live operation.

11. **Supporting infrastructure**
   - The repository includes Sphinx documentation, CI/CD publishing workflows, Debian packaging, pre-commit tooling, and release/version metadata.
   - These pieces support distribution and documentation, but they do not change the runtime architecture; they mainly wrap the Python package for delivery.

12. **How to draw the main diagram**
   - A good architecture diagram should show external resources feeding into connectors, connectors feeding the data pipeline, the data pipeline feeding components and application views, and the core/config/registry layer under all of them as shared runtime infrastructure.
   - Treat `core/` as the control plane, `connectors/` as the integration plane, `data/` as the transformation plane, `components/` as the domain plane, and `application/` as the presentation plane.

Main entry points: [`lories/connectors/connector.py`](https://github.com/isc-konstanz/lories/blob/main/lories/connectors/connector.py) (Connector core), [`lories/data/processors/processor.py`](https://github.com/isc-konstanz/lories/blob/main/lories/data/processors/processor.py) (Processors), [`lories/data/channels/channel.py`](https://github.com/isc-konstanz/lories/blob/main/lories/data/channels/channel.py) (Channels), [`lories/core/configs/configurator.py`](https://github.com/isc-konstanz/lories/blob/main/lories/core/configs/configurator.py) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime core"]
  node_main(("Startup<br/>entrypoint<br/>[__main__.py]"))
  node_configurator["Config<br/>[configurator.py]"]
  node_registry["Registry<br/>[registry.py]"]
  node_activator["Activator<br/>lifecycle control<br/>[activator.py]"]
  node_resource["Resources<br/>shared runtime<br/>[resource.py]"]
end

subgraph group_connectors["Connectors"]
  node_connector_base["Connector core<br/>integration base<br/>[connector.py]"]
  node_csv_conn["CSV<br/>file connector<br/>[csv.py]"]
  node_sql_conn[("SQL<br/>database connector<br/>[database.py]")]
  node_mqtt_conn["MQTT<br/>protocol connector<br/>[mqtt.py]"]
end

subgraph group_data["Data pipeline"]
  node_channel_core["Channels<br/>data ingress<br/>[channel.py]"]
  node_converter_core["Converters<br/>normalization<br/>[converter.py]"]
  node_processor_core["Processors<br/>enrichment<br/>[processor.py]"]
  node_listener_core(("Listeners<br/>reaction<br/>[listener.py]"))
  node_retention[("Retention<br/>storage policy<br/>[retention.py]")]
end

subgraph group_components["Domain components"]
  node_weather["Weather<br/>domain module<br/>[weather.py]"]
  node_tariff["Tariff<br/>domain module<br/>[tariff.py]"]
end

subgraph group_application["Application UI"]
  node_ui_registry["Page registry<br/>ui routing<br/>[registry.py]"]
  node_ui_view["Views<br/>presentation<br/>[view.py]"]
  node_app_main["App main<br/>application shell<br/>[main.py]"]
end

subgraph group_io["Export I/O"]
  node_csv_io["CSV export<br/>reporting I/O<br/>[csv.py]"]
end

node_main -->|"loads"| node_configurator
node_main -->|"starts"| node_app_main
node_configurator -->|"registers"| node_registry
node_configurator -->|"configures"| node_activator
node_activator -->|"manages"| node_resource
node_registry -->|"wires"| node_connector_base
node_registry -->|"wires"| node_channel_core
node_connector_base -->|"implements"| node_csv_conn
node_connector_base -->|"implements"| node_sql_conn
node_connector_base -->|"implements"| node_mqtt_conn
node_connector_base -->|"feeds"| node_channel_core
node_channel_core -->|"normalizes"| node_converter_core
node_converter_core -->|"reshapes"| node_processor_core
node_processor_core -->|"publishes"| node_listener_core
node_processor_core -->|"persists"| node_retention
node_channel_core -->|"stores"| node_retention
node_connector_base -->|"supports"| node_weather
node_connector_base -->|"supports"| node_tariff
node_weather -->|"renders"| node_ui_view
node_tariff -->|"renders"| node_ui_view
node_ui_registry -->|"composes"| node_ui_view
node_app_main -->|"serves"| node_ui_registry
node_processor_core -->|"exports"| node_csv_io
node_retention -.->|"serializes"| node_csv_io

click node_main "https://github.com/isc-konstanz/lories/blob/main/lories/__main__.py"
click node_configurator "https://github.com/isc-konstanz/lories/blob/main/lories/core/configs/configurator.py"
click node_registry "https://github.com/isc-konstanz/lories/blob/main/lories/core/register/registry.py"
click node_activator "https://github.com/isc-konstanz/lories/blob/main/lories/core/activator.py"
click node_resource "https://github.com/isc-konstanz/lories/blob/main/lories/core/resource.py"
click node_connector_base "https://github.com/isc-konstanz/lories/blob/main/lories/connectors/connector.py"
click node_csv_conn "https://github.com/isc-konstanz/lories/blob/main/lories/connectors/csv.py"
click node_sql_conn "https://github.com/isc-konstanz/lories/blob/main/lories/connectors/sql/database.py"
click node_mqtt_conn "https://github.com/isc-konstanz/lories/blob/main/lories/connectors/mqtt.py"
click node_channel_core "https://github.com/isc-konstanz/lories/blob/main/lories/data/channels/channel.py"
click node_converter_core "https://github.com/isc-konstanz/lories/blob/main/lories/data/converters/converter.py"
click node_processor_core "https://github.com/isc-konstanz/lories/blob/main/lories/data/processors/processor.py"
click node_listener_core "https://github.com/isc-konstanz/lories/blob/main/lories/data/listeners/listener.py"
click node_retention "https://github.com/isc-konstanz/lories/blob/main/lories/data/retention.py"
click node_weather "https://github.com/isc-konstanz/lories/blob/main/lories/components/weather/weather.py"
click node_tariff "https://github.com/isc-konstanz/lories/blob/main/lories/components/tariff/tariff.py"
click node_ui_registry "https://github.com/isc-konstanz/lories/blob/main/lories/application/view/pages/registry.py"
click node_ui_view "https://github.com/isc-konstanz/lories/blob/main/lories/application/view/pages/view.py"
click node_app_main "https://github.com/isc-konstanz/lories/blob/main/lories/application/main.py"
click node_csv_io "https://github.com/isc-konstanz/lories/blob/main/lories/io/csv.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_configurator,node_registry,node_activator,node_resource toneBlue
class node_connector_base,node_csv_conn,node_sql_conn,node_mqtt_conn toneAmber
class node_channel_core,node_converter_core,node_processor_core,node_listener_core,node_retention toneMint
class node_weather,node_tariff toneRose
class node_ui_registry,node_ui_view,node_app_main toneIndigo
class node_csv_io toneTeal
```

## Components

### Runtime core

Bootstrap, configuration, lifecycle, and shared registry primitives.

- [Startup](https://github.com/isc-konstanz/lories/blob/main/lories/__main__.py): entrypoint · Package entrypoint and bootstrap path. · `lories/__main__.py`
- [Config](https://github.com/isc-konstanz/lories/blob/main/lories/core/configs/configurator.py): config loader · Loads settings, directories, TOML config, and logging defaults. · `lories/core/configs/configurator.py`
- [Registry](https://github.com/isc-konstanz/lories/blob/main/lories/core/register/registry.py): component registry · Central registration and lookup backbone for runtime objects. · `lories/core/register/registry.py`
- [Activator](https://github.com/isc-konstanz/lories/blob/main/lories/core/activator.py): lifecycle control · Coordinates application and resource lifecycle. · `lories/core/activator.py`
- [Resources](https://github.com/isc-konstanz/lories/blob/main/lories/core/resource.py): shared runtime · Typed resource and context abstractions used across subsystems. · `lories/core/resource.py`

### Connectors

External-system adapters and protocol boundaries.

- [Connector core](https://github.com/isc-konstanz/lories/blob/main/lories/connectors/connector.py): integration base · Base connector abstractions and access boundaries. · `lories/connectors/connector.py`
- [CSV](https://github.com/isc-konstanz/lories/blob/main/lories/connectors/csv.py): file connector · Tabular file ingestion and export connector. · `lories/connectors/csv.py`
- [SQL](https://github.com/isc-konstanz/lories/blob/main/lories/connectors/sql/database.py): database connector · Database connector family for relational access. · `lories/connectors/sql/database.py`
- [MQTT](https://github.com/isc-konstanz/lories/blob/main/lories/connectors/mqtt.py): protocol connector · Message-bus connector for brokered telemetry. · `lories/connectors/mqtt.py`

### Data pipeline

Channels, conversion, processing, persistence, and reactions.

- [Channels](https://github.com/isc-konstanz/lories/blob/main/lories/data/channels/channel.py): data ingress · Bridges connector output into managed data streams. · `lories/data/channels/channel.py`
- [Converters](https://github.com/isc-konstanz/lories/blob/main/lories/data/converters/converter.py): normalization · Transforms raw readings into domain values. · `lories/data/converters/converter.py`
- [Processors](https://github.com/isc-konstanz/lories/blob/main/lories/data/processors/processor.py): enrichment · Applies transformations and higher-level processing. · `lories/data/processors/processor.py`
- [Listeners](https://github.com/isc-konstanz/lories/blob/main/lories/data/listeners/listener.py): reaction · Consumes processed values for live reactions. · `lories/data/listeners/listener.py`
- [Retention](https://github.com/isc-konstanz/lories/blob/main/lories/data/retention.py): storage policy · Controls persistence, replication, and long-lived data handling. · `lories/data/retention.py`

### Domain components

Higher-level weather and tariff modules built on the runtime and data layers.

- [Weather](https://github.com/isc-konstanz/lories/blob/main/lories/components/weather/weather.py): domain module · Weather domain built from provider-based integrations. · `lories/components/weather/weather.py`
- [Tariff](https://github.com/isc-konstanz/lories/blob/main/lories/components/tariff/tariff.py): domain module · Tariff and pricing domain built from provider-based integrations. · `lories/components/tariff/tariff.py`

### Application UI

Presentation layer and page composition.

- [Page registry](https://github.com/isc-konstanz/lories/blob/main/lories/application/view/pages/registry.py): ui routing · Registers and organizes pages and view composition. · `lories/application/view/pages/registry.py`
- [Views](https://github.com/isc-konstanz/lories/blob/main/lories/application/view/pages/view.py): presentation · Reusable page, layout, and component composition. · `lories/application/view/pages/view.py`
- [App main](https://github.com/isc-konstanz/lories/blob/main/lories/application/main.py): application shell · Application-level startup and wiring for the presentation layer. · `lories/application/main.py`

### Export I/O

File-oriented output and reporting helpers.

- [CSV export](https://github.com/isc-konstanz/lories/blob/main/lories/io/csv.py): reporting I/O · File-oriented export and reporting helper. · `lories/io/csv.py`

## Connections

- Startup → Config: loads · Bootstrap reads configuration early.
- Startup → App main: starts · Entrypoint delegates into application startup.
- Config → Registry: registers · Configuration feeds registry-backed wiring.
- Config → Activator: configures · Startup settings shape lifecycle behavior.
- Activator → Resources: manages · Lifecycle operates on shared resources and contexts.
- Registry → Connector core: wires · Registry holds connector implementations.
- Registry → Channels: wires · Registry links channel definitions and handlers.
- Connector core → CSV: implements · CSV is one concrete connector family.
- Connector core → SQL: implements · SQL is one concrete connector family.
- Connector core → MQTT: implements · MQTT is one concrete connector family.
- Connector core → Channels: feeds · Connectors provide raw inputs to channels.
- Channels → Converters: normalizes · Channels hand off values for conversion.
- Converters → Processors: reshapes · Converted data flows into processing stages.
- Processors → Listeners: publishes · Processed values can trigger listeners.
- Processors → Retention: persists · Processors can hand off to storage and replication policy.
- Channels → Retention: stores · Channel data can be retained long-term.
- Connector core → Weather: supports · Weather domain depends on connector-backed providers.
- Connector core → Tariff: supports · Tariff domain depends on connector-backed providers.
- Weather → Views: renders · Weather data is presented through views.
- Tariff → Views: renders · Tariff data is presented through views.
- Page registry → Views: composes · Page registry organizes reusable views.
- App main → Page registry: serves · Application startup exposes registered pages.
- Processors → CSV export: exports · Processed results can be written for reporting.
- Retention → CSV export: serializes · Stored data can be exported to files.
