diff --git a/Architecture-Configuration-Model-and-Tagcodering.md b/Architecture-Configuration-Model-and-Tagcodering.md new file mode 100644 index 0000000..ad2fa47 --- /dev/null +++ b/Architecture-Configuration-Model-and-Tagcodering.md @@ -0,0 +1,39 @@ +# EVOLV Configuration Model and Tagcodering + +The intended long-term configuration authority for EVOLV is the database-backed `tagcodering` model. + +## Role Of Tagcodering + +`tagcodering` is intended to hold: + +- machine information +- asset metadata +- runtime configuration +- the basis for configuration exchange across edge, site, and central layers + +## Configuration Direction + +```mermaid +flowchart LR + CFG["Tagcodering"] --> API["Config / Integration API"] + API --> SITE["Site Layer"] + SITE --> EDGE["Edge Layer"] + EDGE --> NODES["EVOLV Node-RED Nodes"] +``` + +## Architectural Principle + +Node-RED flows should consume configuration, not silently become the only source of truth for configuration. + +That means EVOLV should move toward: + +- database-backed machine and asset metadata +- versioned configuration flows +- controlled rollout from central to site to edge +- less duplication between flows and platform data + +## Current Status + +`tagcodering` already exists partially but still needs more work to behave as the full configuration backbone. + +That gap should be treated as platform work, not as a secondary cleanup task. diff --git a/Architecture-Platform-Overview.md b/Architecture-Platform-Overview.md new file mode 100644 index 0000000..b441558 --- /dev/null +++ b/Architecture-Platform-Overview.md @@ -0,0 +1,73 @@ +# EVOLV Platform Overview + +EVOLV is a layered automation platform: + +- edge for plant-side execution +- site for local aggregation and operational resilience +- central for APIs, analytics, advisory intelligence, and governance + +## Topology + +```mermaid +flowchart LR + subgraph OT["OT / Field"] + PLC["PLC / IO"] + DEV["Sensors / Machines"] + end + + subgraph EDGE["Edge Layer"] + ENR["Edge Node-RED"] + EDB["Local InfluxDB"] + EUI["Local Monitoring / Local Dashboards"] + EBR["Optional Local Broker"] + end + + subgraph SITE["Site Layer"] + SNR["Site Node-RED / CoreSync"] + SDB["Site InfluxDB"] + SUI["Site Dashboards / SCADA Support"] + SBR["Site Broker"] + end + + subgraph CENTRAL["Central Layer"] + API["API / Integration Gateway"] + INTEL["Overview Intelligence / Advisory Logic"] + CDB["Central InfluxDB"] + CGR["Central Grafana"] + CFG["Tagcodering"] + GIT["Gitea + CI/CD"] + IAM["IAM"] + end + + DEV --> PLC + PLC --> ENR + ENR --> EDB + ENR --> EUI + ENR --> EBR + ENR <--> SNR + EDB <--> SDB + SNR --> SDB + SNR --> SUI + SNR --> SBR + SNR <--> API + API --> INTEL + API <--> CFG + SDB <--> CDB + CDB --> CGR + IAM --> API + GIT --> ENR + GIT --> SNR +``` + +## Key Decisions + +- Local InfluxDB is required for operational resilience. +- Central is the advisory and API-entry layer, not the direct field caller. +- `tagcodering` is the intended database-backed configuration authority. +- EVOLV should be designed as a platform, not only as a collection of Node-RED nodes. + +## Why This Structure + +- Edge remains useful and safe during central outages. +- Site absorbs plant-specific complexity and protects field systems. +- Central provides fleet-level visibility, governance, and integration. diff --git a/Architecture-Security-and-Access-Boundaries.md b/Architecture-Security-and-Access-Boundaries.md new file mode 100644 index 0000000..75865aa --- /dev/null +++ b/Architecture-Security-and-Access-Boundaries.md @@ -0,0 +1,36 @@ +# EVOLV Security and Access Boundaries + +EVOLV should expose central services, not field-edge systems, to external consumers. + +## Access Boundary + +```mermaid +flowchart TD + EXT["External APIs / Enterprise Requests"] --> API["Central API Gateway"] + API --> AUTH["AuthN/AuthZ / Policy Checks"] + AUTH --> INTEL["Central Advisory / Decision Support"] + INTEL --> SITE["Site Integration Layer"] + SITE --> EDGE["Edge Runtime"] + EDGE --> PLC["PLC / Field Assets"] + + EXT -. no direct access .-> EDGE + EXT -. no direct access .-> PLC +``` + +## Principles + +- External integrations terminate centrally. +- Central authenticates, authorizes, and mediates requests. +- Site and edge layers receive bounded requests, advice, or setpoints. +- Edge remains protected behind intermediate layers. + +## Why This Matters + +- lower exposure of OT assets +- better separation between enterprise and plant networks +- easier enforcement of policy, logging, and audit controls +- safer long-term path for overview intelligence and API ecosystems + +## Operational Constraint + +Central guidance should remain advisory-first. Local site and edge layers must still behave safely when central is degraded or unavailable. diff --git a/Architecture-Telemetry-and-Smart-Storage.md b/Architecture-Telemetry-and-Smart-Storage.md new file mode 100644 index 0000000..bec3fbe --- /dev/null +++ b/Architecture-Telemetry-and-Smart-Storage.md @@ -0,0 +1,50 @@ +# EVOLV Telemetry and Smart Storage + +EVOLV uses InfluxDB on multiple levels: + +- local for resilience and digital-twin use +- site for plant diagnostics and continuity +- central for fleet analytics and advisory intelligence + +## Multi-Level Telemetry Flow + +```mermaid +flowchart LR + RAW["Raw Signal"] --> EVAL["Edge Signal Evaluation"] + EVAL --> KEEP["Keep critical change points"] + EVAL --> REDUCE["Reduce reconstructable flat spans"] + KEEP --> L0["Local InfluxDB"] + REDUCE --> L0 + L0 --> L1["Site InfluxDB"] + L1 --> L2["Central InfluxDB"] + L2 --> DASH["Dashboards / Analytics / Intelligence"] +``` + +## Design Intent + +The target is not only naive event storage with a fixed deadband such as 1%. + +The intended model is signal-aware: + +- evaluate slope and change behavior +- keep points that carry meaningful process information +- avoid storing large runs of low-information points +- preserve enough context that downstream reconstruction remains auditable + +## Benefits + +- lower storage volume without throwing away useful process behavior +- better local resilience because important state transitions are preserved +- stronger support for digital-twin and analytics use cases +- more useful site and fleet history + +## Risks To Manage + +- reconstruction rules must be explicit +- acceptable reconstruction error must be defined per signal class +- compliance-critical signals may need stricter raw retention +- the authoritative layer for each time horizon must be clear + +## Direction + +Smart storage should be treated as a first-class EVOLV architecture feature, not as an afterthought on top of InfluxDB. diff --git a/Home.md b/Home.md index b66016e..cbdb336 100644 --- a/Home.md +++ b/Home.md @@ -14,9 +14,9 @@ EVOLV is an industrial automation platform built as a custom Node-RED package fo | **Thermodynamics** | CoolProp | | **Target** | Waterschap Brabantse Delta (NL) | -## Architecture - -EVOLV provides **12 custom Node-RED nodes** plus a shared utility library (`generalFunctions`). Each node follows a **3-tier architecture**: +## Architecture + +EVOLV provides **12 custom Node-RED nodes** plus a shared utility library (`generalFunctions`). Each node follows a **3-tier architecture**: 1. **Entry file** - Node-RED registration, HTTP endpoints for editor menus 2. **nodeClass** - Node-RED adapter layer (handles `RED.*` API calls) @@ -40,8 +40,55 @@ All internal calculations use SI-derived canonical units: |----------|------| | Pressure | Pa | | Flow | m3/s | -| Power | W | -| Temperature | K | +| Power | W | +| Temperature | K | + +## Platform Architecture + +EVOLV is not only a Node-RED package. It is a layered platform with: + +- edge execution close to PLCs and field assets +- site aggregation for resilience and plant-local operations +- central services for APIs, intelligence, analytics, governance, and lifecycle management + +Architecture pages: + +- [Platform Overview](Architecture-Platform-Overview) +- [Telemetry and Smart Storage](Architecture-Telemetry-and-Smart-Storage) +- [Security and Access Boundaries](Architecture-Security-and-Access-Boundaries) +- [Configuration Model and Tagcodering](Architecture-Configuration-Model-and-Tagcodering) + +```mermaid +flowchart LR + subgraph EDGE["Edge"] + PLC["PLC / IO"] + ENR["Node-RED"] + EDB["Local InfluxDB"] + end + + subgraph SITE["Site"] + SNR["CoreSync / Site Node-RED"] + SDB["Site InfluxDB"] + end + + subgraph CENTRAL["Central"] + API["API Gateway"] + CFG["Tagcodering"] + CDB["Central InfluxDB"] + CGR["Grafana"] + INTEL["Overview Intelligence"] + end + + PLC --> ENR + ENR --> EDB + ENR <--> SNR + EDB <--> SDB + SNR <--> API + API <--> CFG + API --> INTEL + SDB <--> CDB + CDB --> CGR +``` ## Node Inventory