EVOLV/wiki/Archive/architecture-deployment-blueprint.md

---
title: EVOLV Deployment Blueprint
created: 2026-03-01
updated: 2026-04-07
status: evolving
tags: [deployment, docker, edge, site, central]
---

> **⚠️ ARCHIVED — pre-refactor (Tier 1–4, 2026-05)**
>
> This page describes the architecture before the platform refactor.
> The current page is the per-node wiki on **[gitea.wbd-rd.nl/RnD](https://gitea.wbd-rd.nl/RnD)** or **[Home](../Home)**.
>
> Kept for historical reference only. **Do not update.**


# EVOLV Deployment Blueprint

## Purpose

This document turns the current EVOLV architecture into a concrete deployment model.

It focuses on:

- target infrastructure layout
- container/service topology
- environment and secret boundaries
- rollout order from edge to site to central

It is the local source document behind the wiki deployment pages.

## 1. Deployment Principles

- edge-first operation: plant logic must continue when central is unavailable
- site mediation: site services protect field systems and absorb plant-specific complexity
- central governance: external APIs, analytics, IAM, CI/CD, and shared dashboards terminate centrally
- layered telemetry: InfluxDB exists where operationally justified at edge, site, and central
- configuration authority: `tagcodering` should become the source of truth for configuration
- secrets hygiene: tracked manifests contain variables only; secrets live in server-side env or secret stores

## 2. Layered Deployment Model

### 2.1 Edge node

Purpose:

- interface with PLCs and field assets
- execute local Node-RED logic
- retain local telemetry for resilience and digital-twin use cases

Recommended services:

- `evolv-edge-nodered`
- `evolv-edge-influxdb`
- optional `evolv-edge-grafana`
- optional `evolv-edge-broker`

Should not host:

- public API ingress
- central IAM
- source control or CI/CD

### 2.2 Site node

Purpose:

- aggregate one or more edge nodes
- host plant-local dashboards and engineering visibility
- mediate traffic between edge and central

Recommended services:

- `evolv-site-nodered` or `coresync-site`
- `evolv-site-influxdb`
- `evolv-site-grafana`
- optional `evolv-site-broker`

### 2.3 Central platform

Purpose:

- fleet-wide analytics
- API and integration ingress
- engineering lifecycle and releases
- identity and governance

Recommended services:

- reverse proxy / ingress
- API gateway
- IAM
- central InfluxDB
- central Grafana
- Gitea
- CI/CD runner/controller
- optional broker for asynchronous site/central workflows
- configuration services over `tagcodering`

## 3. Target Container Topology

### 3.1 Edge host

Minimum viable edge stack:

```text
edge-host-01
  - Node-RED
  - InfluxDB
  - optional Grafana
```

Preferred production edge stack:

```text
edge-host-01
  - Node-RED
  - InfluxDB
  - local health/export service
  - optional local broker
  - optional local dashboard service
```

### 3.2 Site host

Minimum viable site stack:

```text
site-host-01
  - Site Node-RED / CoreSync
  - Site InfluxDB
  - Site Grafana
```

Preferred production site stack:

```text
site-host-01
  - Site Node-RED / CoreSync
  - Site InfluxDB
  - Site Grafana
  - API relay / sync service
  - optional site broker
```

### 3.3 Central host group

Central should not be one giant undifferentiated host forever. It should trend toward at least these responsibility groups:

```text
central-ingress
  - reverse proxy
  - API gateway
  - IAM

central-observability
  - central InfluxDB
  - Grafana

central-engineering
  - Gitea
  - CI/CD
  - deployment orchestration

central-config
  - tagcodering-backed config services
```

For early rollout these may be colocated, but the responsibility split should remain clear.

## 4. Compose Strategy

The current repository shows:

- `docker-compose.yml` as a development stack
- `temp/cloud.yml` as a broad central-stack example

For production, EVOLV should not rely on one flat compose file for every layer.

Recommended split:

- `compose.edge.yml`
- `compose.site.yml`
- `compose.central.yml`
- optional overlay files for site-specific differences

Benefits:

- clearer ownership per layer
- smaller blast radius during updates
- easier secret and env separation
- easier rollout per site

## 5. Environment And Secrets Strategy

### 5.1 Current baseline

`temp/cloud.yml` now uses environment variables instead of inline credentials. That is the minimum acceptable baseline.

### 5.2 Recommended production rule

- tracked compose files contain `${VARIABLE}` placeholders only
- real secrets live in server-local `.env` files or a managed secret store
- no shared default production passwords in git
- separate env files per layer and per environment

Suggested structure:

```text
/opt/evolv/
  compose.edge.yml
  compose.site.yml
  compose.central.yml
  env/
    edge.env
    site.env
    central.env
```

## 6. Recommended Network Flow

### 6.1 Northbound

- edge publishes or syncs upward to site
- site aggregates and forwards selected data to central
- central exposes APIs and dashboards to approved consumers

### 6.2 Southbound

- central issues advice, approved config, or mediated requests
- site validates and relays to edge where appropriate
- edge remains the execution point near PLCs

### 6.3 Forbidden direct path

- enterprise or internet clients should not directly query PLC-connected edge runtimes

## 7. Rollout Order

### Phase 1: Edge baseline

- deploy edge Node-RED
- deploy local InfluxDB
- validate PLC connectivity
- validate local telemetry and resilience

### Phase 2: Site mediation

- deploy site Node-RED / CoreSync
- connect one or more edge nodes
- validate site-local dashboards and outage behavior

### Phase 3: Central services

- deploy ingress, IAM, API, Grafana, central InfluxDB
- deploy Gitea and CI/CD services
- validate controlled northbound access

### Phase 4: Configuration backbone

- connect runtime layers to `tagcodering`
- reduce config duplication in flows
- formalize config promotion and rollback

### Phase 5: Smart telemetry policy

- classify signals
- define reconstruction rules
- define authoritative layer per horizon
- validate analytics and auditability

## 8. Immediate Technical Recommendations

- treat `docker/settings.js` as development-only and create hardened production settings separately
- split deployment manifests by layer
- define env files per layer and environment
- formalize healthchecks and backup procedures for every persistent service
- define whether broker usage is required at edge, site, central, or only selectively

## 9. Next Technical Work Items

1. create draft `compose.edge.yml`, `compose.site.yml`, and `compose.central.yml`
2. define server directory layout and env-file conventions
3. define production Node-RED settings profile
4. define site-to-central sync path
5. define deployment and rollback runbook