# 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