Add architecture review and wiki draft

2026-03-23 11:23:24 +01:00
parent 99aedf46c3
commit 75458713be
7 changed files with 920 additions and 0 deletions
--- a/architecture/wiki-platform-overview.md
+++ b/architecture/wiki-platform-overview.md
@@ -0,0 +1,150 @@
+# EVOLV Platform Architecture
+
+## At A Glance
+
+EVOLV is not only a Node-RED package. It is a layered automation platform:
+
+- edge for plant-side execution
+- site for local aggregation and resilience
+- central for coordination, analytics, APIs, and governance
+
+```mermaid
+flowchart LR
+    subgraph EDGE["Edge"]
+        PLC["PLC / IO"]
+        ENR["Node-RED"]
+        EDB["Local InfluxDB"]
+        EUI["Local Monitoring"]
+    end
+
+    subgraph SITE["Site"]
+        SNR["CoreSync / Site Node-RED"]
+        SDB["Site InfluxDB"]
+        SUI["Site Dashboards"]
+    end
+
+    subgraph CENTRAL["Central"]
+        API["API Gateway"]
+        CFG["Tagcodering"]
+        CDB["Central InfluxDB"]
+        CGR["Grafana"]
+        INTEL["Overview Intelligence"]
+        GIT["Gitea + CI/CD"]
+    end
+
+    PLC --> ENR
+    ENR --> EDB
+    ENR --> EUI
+    ENR <--> SNR
+    EDB <--> SDB
+    SNR --> SUI
+    SNR <--> API
+    API <--> CFG
+    API --> INTEL
+    SDB <--> CDB
+    CDB --> CGR
+    GIT --> ENR
+    GIT --> SNR
+```
+
+## Core Principles
+
+### 1. Edge-first operation
+
+The edge layer must remain useful and safe when central systems are down.
+
+That means:
+
+- local logic remains operational
+- local telemetry remains queryable
+- local dashboards can keep working
+
+### 2. Multi-level telemetry
+
+InfluxDB is expected on multiple levels:
+
+- local for resilience and digital-twin use
+- site for plant diagnostics
+- central for fleet analytics and advisory logic
+
+### 3. Smart storage
+
+Telemetry should not be stored only with naive deadband rules.
+
+The target model is signal-aware:
+
+- preserve critical change points
+- reduce low-information flat sections
+- allow downstream reconstruction where justified
+
+```mermaid
+flowchart LR
+    SIG["Process Signal"] --> EVAL["Slope / Event Evaluation"]
+    EVAL --> KEEP["Keep critical points"]
+    EVAL --> REDUCE["Reduce reconstructable points"]
+    KEEP --> L0["Local InfluxDB"]
+    REDUCE --> L0
+    L0 --> L1["Site InfluxDB"]
+    L1 --> L2["Central InfluxDB"]
+```
+
+### 4. Central is the safe entry point
+
+External systems should enter through central APIs, not by directly calling field-edge systems.
+
+```mermaid
+flowchart TD
+    EXT["External Request"] --> API["Central API Gateway"]
+    API --> AUTH["Auth / Policy"]
+    AUTH --> SITE["Site Layer"]
+    SITE --> EDGE["Edge Layer"]
+    EDGE --> PLC["Field Assets"]
+
+    EXT -. blocked .-> EDGE
+    EXT -. blocked .-> PLC
+```
+
+### 5. Configuration belongs in `tagcodering`
+
+The intended configuration source of truth is the database-backed `tagcodering` model:
+
+- machine metadata
+- asset configuration
+- runtime-consumable configuration
+- future central/site configuration services
+
+This already exists partially but still needs more work before it fully serves that role.
+
+## Layer Roles
+
+### Edge
+
+- PLC connectivity
+- local logic
+- protocol translation
+- local telemetry buffering
+- local monitoring and digital-twin support
+
+### Site
+
+- aggregation of edge systems
+- local dashboards and diagnostics
+- mediation between OT and central
+- protected handoff for central requests
+
+### Central
+
+- enterprise/API gateway
+- fleet dashboards
+- analytics and intelligence
+- source control and CI/CD
+- configuration governance through `tagcodering`
+
+## Why This Matters
+
+This architecture gives EVOLV:
+
+- better resilience
+- safer external integration
+- better data quality for analytics
+- a path from Node-RED package to platform