RnD/EVOLV
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases Wiki Activity

Add architecture review and wiki draft

Browse Source
This commit is contained in:
znetsixe
2026-03-23 11:23:24 +01:00
parent 99aedf46c3
commit 75458713be
7 changed files with 920 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
.agents/decisions/DECISION-20260323-architecture-layering-resilience-and-config-authority.md Normal file
View File

@@ -0,0 +1,36 @@
# DECISION-20260323-architecture-layering-resilience-and-config-authority
## Context
- Task/request: refine the EVOLV architecture baseline using the current stack drawings and owner guidance.
- Impacted files/contracts: architecture documentation, future wiki structure, telemetry/storage strategy, security boundaries, and configuration authority assumptions.
- Why a decision is required now: the architecture can no longer stay at a generic "Node-RED plus cloud" level; several operating principles were clarified by the owner and need to be treated as architectural defaults.
## Options
1. Keep the architecture intentionally broad and tool-centric
- Benefits: fewer early commitments.
- Risks: blurred boundaries for resilience, data ownership, and security; easier to drift into contradictory implementations.
- Rollout notes: wiki remains descriptive but not decision-shaping.
2. Adopt explicit defaults for resilience, API boundary, telemetry layering, and configuration authority
- Benefits: clearer target operating model; easier to design stack services and wiki pages consistently; aligns diagrams with intended operational behavior.
- Risks: some assumptions may outpace current implementation and therefore create an architecture debt backlog.
- Rollout notes: document gaps clearly and treat incomplete systems as planned workstreams rather than pretending they already exist.
## Decision
- Selected option: Option 2.
- Decision owner: repository owner confirmed during architecture review.
- Date: 2026-03-23.
- Rationale: the owner clarified concrete architecture goals that materially affect security, resilience, and platform structure. The documentation should encode those as defaults instead of leaving them implicit.
## Consequences
- Compatibility impact: low immediate code impact, but future implementations should align to these defaults.
- Safety/security impact: improved boundary clarity by making central the integration entry point and keeping edge protected behind site/central mediation.
- Data/operations impact: multi-level InfluxDB and smart-storage behavior become first-class design concerns; `tagcodering` becomes the intended configuration backbone.
## Implementation Notes
- Required code/doc updates: update the architecture review doc, add visual wiki-ready diagrams, and track follow-up work for incomplete `tagcodering` integration and telemetry policy design.
- Validation evidence required: architecture docs reflect the agreed principles and diagrams; no contradiction with current repo evidence for implemented components.
## Rollback / Migration
- Rollback strategy: return to a generic descriptive architecture document without explicit defaults.
- Migration/deprecation plan: implement these principles incrementally, starting with configuration authority, telemetry policy, and site/central API boundaries.

36
.agents/decisions/DECISION-20260323-compose-secrets-via-env.md Normal file
View File

@@ -0,0 +1,36 @@
# DECISION-20260323-compose-secrets-via-env
## Context
- Task/request: harden the target-state stack example so credentials are not stored directly in `temp/cloud.yml`.
- Impacted files/contracts: `temp/cloud.yml`, deployment/operations practice for target-state infrastructure examples.
- Why a decision is required now: the repository contained inline credentials in a tracked compose file, which conflicts with the intended security posture and creates avoidable secret-leak risk.
## Options
1. Keep credentials inline in the compose file
- Benefits: simplest to run as a standalone example.
- Risks: secrets leak into git history, reviews, copies, and local machines; encourages unsafe operational practice.
- Rollout notes: none, but the risk remains permanent once committed.
2. Move credentials to server-side environment variables and keep only placeholders in compose
- Benefits: aligns the manifest with a safer deployment pattern; keeps tracked config portable across environments; supports secret rotation without editing the compose file.
- Risks: operators must manage `.env` or equivalent secret injection correctly.
- Rollout notes: provide an example env file and document that the real `.env` stays on the server and out of version control.
## Decision
- Selected option: Option 2.
- Decision owner: repository owner confirmed during task discussion.
- Date: 2026-03-23.
- Rationale: the target architecture should model the right operational pattern. Inline secrets in repository-tracked compose files are not acceptable for EVOLV's intended OT/IT deployment posture.
## Consequences
- Compatibility impact: low; operators now need to supply environment variables when deploying `temp/cloud.yml`.
- Safety/security impact: improved secret hygiene and lower credential exposure risk.
- Data/operations impact: deployment requires an accompanying `.env` on the server or explicit `--env-file` usage.
## Implementation Notes
- Required code/doc updates: replace inline secrets in `temp/cloud.yml`; add `temp/cloud.env.example`; keep the real `.env` untracked on the server.
- Validation evidence required: inspect compose file for `${...}` placeholders and verify no real credentials remain in tracked files touched by this change.
## Rollback / Migration
- Rollback strategy: reintroduce inline values, though this is not recommended.
- Migration/deprecation plan: create a server-local `.env` from `temp/cloud.env.example`, fill in real values, and run compose from that environment.