EVOLV/architecture/deployment-blueprint.md

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:

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

Preferred production edge stack:

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:

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

Preferred production site stack:

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:

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:

/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