From eb756c8bf6b542c24a45ac1b5d414fe49a5e9098 Mon Sep 17 00:00:00 2001
From: znetsixe <zn375ix3@gmail.com>
Date: Mon, 23 Mar 2026 11:54:40 +0100
Subject: [PATCH] Add deployment blueprint and topology pages

---
 Architecture-Container-Topology.md   |  75 ++++++++++++++++
 Architecture-Deployment-Blueprint.md | 127 +++++++++++++++++++++++++++
 Home.md                              |   2 +
 3 files changed, 204 insertions(+)
 create mode 100644 Architecture-Container-Topology.md
 create mode 100644 Architecture-Deployment-Blueprint.md

diff --git a/Architecture-Container-Topology.md b/Architecture-Container-Topology.md
new file mode 100644
index 0000000..6c6cbf9
--- /dev/null
+++ b/Architecture-Container-Topology.md
@@ -0,0 +1,75 @@
+# EVOLV Container Topology
+
+This page translates the deployment blueprint into a practical container/service split.
+
+## Current Repository Baseline
+
+Today the repository contains:
+
+- a development stack in `docker-compose.yml`
+- a broad central-stack example in `temp/cloud.yml`
+
+Those are useful references, but production should be split by layer.
+
+## Recommended Service Split
+
+### Edge host
+
+```text
+edge-host-01
+  - evolv-edge-nodered
+  - evolv-edge-influxdb
+  - optional evolv-edge-grafana
+  - optional evolv-edge-broker
+```
+
+### Site host
+
+```text
+site-host-01
+  - evolv-site-nodered
+  - evolv-site-influxdb
+  - evolv-site-grafana
+  - optional evolv-site-broker
+```
+
+### Central host groups
+
+```text
+central-ingress
+  - reverse proxy
+  - API gateway
+  - IAM
+
+central-observability
+  - central InfluxDB
+  - Grafana
+
+central-engineering
+  - Gitea
+  - CI/CD
+
+central-config
+  - tagcodering-backed config services
+```
+
+## Why Split By Layer
+
+- better fault isolation
+- easier upgrades
+- clearer secret boundaries
+- less confusion between OT-adjacent and enterprise services
+
+## Production Guidance
+
+- keep development Node-RED settings separate from production settings
+- add healthchecks for every persistent service
+- back up every persistent volume
+- avoid exposing edge services publicly
+- use env files or secret injection, not inline credentials
+
+## Related Pages
+
+- [Deployment Blueprint](Architecture-Deployment-Blueprint)
+- [Security and Access Boundaries](Architecture-Security-and-Access-Boundaries)
+- [Deployment Controls Checklist](Architecture-Deployment-Controls-Checklist)
diff --git a/Architecture-Deployment-Blueprint.md b/Architecture-Deployment-Blueprint.md
new file mode 100644
index 0000000..698f27d
--- /dev/null
+++ b/Architecture-Deployment-Blueprint.md
@@ -0,0 +1,127 @@
+# EVOLV Deployment Blueprint
+
+This page turns the architecture into a concrete deployment model.
+
+## Layered Deployment Model
+
+### Edge
+
+Purpose:
+
+- PLC and field connectivity
+- local Node-RED execution
+- local InfluxDB for resilience and digital-twin use
+
+Recommended services:
+
+- Node-RED
+- InfluxDB
+- optional local Grafana
+- optional local broker
+
+### Site
+
+Purpose:
+
+- plant-local aggregation
+- mediation between edge and central
+- local dashboards and diagnostics
+
+Recommended services:
+
+- Site Node-RED / CoreSync
+- Site InfluxDB
+- Site Grafana
+- optional broker
+
+### Central
+
+Purpose:
+
+- API ingress
+- IAM and governance
+- fleet analytics and dashboards
+- source control, CI/CD, and configuration services
+
+Recommended services:
+
+- reverse proxy / ingress
+- API gateway
+- IAM
+- central InfluxDB
+- central Grafana
+- Gitea
+- CI/CD
+- `tagcodering`-backed configuration services
+
+## Target Topology
+
+```mermaid
+flowchart LR
+    subgraph EDGE["Edge Host"]
+        ENR["Node-RED"]
+        EDB["InfluxDB"]
+        EGR["Optional Grafana"]
+    end
+
+    subgraph SITE["Site Host"]
+        SNR["Site Node-RED / CoreSync"]
+        SDB["Site InfluxDB"]
+        SGR["Site Grafana"]
+    end
+
+    subgraph CENTRAL["Central Platform"]
+        RP["Reverse Proxy / Ingress"]
+        API["API Gateway"]
+        IAM["IAM"]
+        CDB["Central InfluxDB"]
+        CGR["Grafana"]
+        GIT["Gitea"]
+        CICD["CI/CD"]
+        CFG["Tagcodering Services"]
+    end
+
+    ENR --> EDB
+    ENR <--> SNR
+    EDB <--> SDB
+    SNR --> SGR
+    SNR <--> API
+    RP --> API
+    API --> IAM
+    API <--> CFG
+    SDB <--> CDB
+    CDB --> CGR
+    GIT --> CICD
+```
+
+## Compose Strategy
+
+Do not use one flat compose file for all layers in production.
+
+Preferred split:
+
+- `compose.edge.yml`
+- `compose.site.yml`
+- `compose.central.yml`
+
+This gives clearer ownership, easier secret separation, and safer updates.
+
+## Environment Strategy
+
+- tracked compose files contain variables only
+- real values live in server-local `.env` files or a secret store
+- env files should be separated by layer and environment
+
+## Rollout Order
+
+1. edge baseline
+2. site mediation
+3. central platform
+4. `tagcodering` integration
+5. smart telemetry policy
+
+## Related Pages
+
+- [Deployment Controls Checklist](Architecture-Deployment-Controls-Checklist)
+- [Platform Overview](Architecture-Platform-Overview)
+- [Configuration Model and Tagcodering](Architecture-Configuration-Model-and-Tagcodering)
diff --git a/Home.md b/Home.md
index 0d0d2a9..77b0f27 100644
--- a/Home.md
+++ b/Home.md
@@ -58,6 +58,8 @@ Architecture pages:
 - [Security and Access Boundaries](Architecture-Security-and-Access-Boundaries)
 - [Security and Regulatory Mapping](Architecture-Security-and-Regulatory-Mapping)
 - [Deployment Controls Checklist](Architecture-Deployment-Controls-Checklist)
+- [Deployment Blueprint](Architecture-Deployment-Blueprint)
+- [Container Topology](Architecture-Container-Topology)
 - [Configuration Model and Tagcodering](Architecture-Configuration-Model-and-Tagcodering)
 
 ```mermaid