From a871d6506478a4a93f16d3590bc85252c35b39bf Mon Sep 17 00:00:00 2001
From: Pierre Tenedero <pierre.tenedero@gmail.com>
Date: Tue, 28 Apr 2026 16:08:25 +0800
Subject: [PATCH] Add adr-003-cluster-generation

---
 .config/lingo.dic                             | 10 ++
 .typos.toml                                   |  2 +
 .../adr-003-cluster-generation.md             | 98 +++++++++++++++++++
 3 files changed, 110 insertions(+)
 create mode 100644 .typos.toml
 create mode 100755 docs/architecture/adr-003-cluster-generation.md

diff --git a/.config/lingo.dic b/.config/lingo.dic
index 082de7a..7a10ea8 100644
--- a/.config/lingo.dic
+++ b/.config/lingo.dic
@@ -10,20 +10,28 @@ CLI
 CRICOS
 Curtin
 EECMS
+GCP
+HAR
 IP
 I.P.
 Kubernetes
 LanguageTool
 MermaidJS
+OpenShift
 PlantUML
 PRV12158
+Ratatui
 TEQSA
+Tenedero
 Vandenberg
 agentic
 attrited
 auditable
 componentry
 deployable
+eGUI
+et
+cli
 hunspell
 fred
 integrations
@@ -33,6 +41,8 @@ k3s
 lifecycle
 mise
 modularity
+mprocs
+nanocl
 nlprules
 npm
 observability
diff --git a/.typos.toml b/.typos.toml
new file mode 100644
index 0000000..cd09bbb
--- /dev/null
+++ b/.typos.toml
@@ -0,0 +1,2 @@
+[default.extend-words]
+Ratatui = "Ratatui"
diff --git a/docs/architecture/adr-003-cluster-generation.md b/docs/architecture/adr-003-cluster-generation.md
new file mode 100755
index 0000000..771e660
--- /dev/null
+++ b/docs/architecture/adr-003-cluster-generation.md
@@ -0,0 +1,98 @@
+---
+id: ADR-003
+status: proposed
+date: 2026-04-28
+author: pierre-tenedero
+tags: [architecture]
+---
+
+# Cluster Generation from Scenario Configuration Files
+
+## Context
+
+`edge-toolkit` needs a standardised way to define scenarios through configuration files and reliably transform those
+definitions into runnable deployments.
+
+## Decisions
+
+We will introduce `et-cli` as a cluster generation tool that reads a scenario configuration (YAML) file and produces the
+corresponding deployment artifacts.
+
+### et-cli
+
+`et-cli` is a command line interface tool that serves as the entry point for generating scenarios from an input YAML
+file.
+It provides a consistent and repeatable mechanism for converting scenario definitions into deployable environments.
+
+It currently supports the following deployments:
+
+- mise
+- Docker Compose
+
+#### Example Case: Facility Security
+
+As an example, consider a facility security system with an entrance camera and wearable health trackers for workers.
+This scenario can be defined using the following YAML configuration:
+
+```yaml
+cluster_name: "facility-security-scenario"
+deployment_type: "docker-compose"
+
+agents:
+  - name: "entrance-security-camera"
+    resources:
+      - type: "face-detection"
+
+  - name: "worker-health-tracker"
+    resources:
+      - type: "har1"
+```
+
+From this configuration, `et-cli` infers the required workflow modules based on each agent’s resource definitions.
+In this case, the face detection and HAR modules are automatically selected and executed within `ws-server`.
+
+### Verification and validation
+
+`et-cli` supports regenerating scenarios from a designated directory. During regeneration, it performs a diff against
+existing artifacts to detect drift and identify any stale generated files. This ensures that scenario outputs remain
+up-to-date and consistent with their source definitions.
+
+## Future considerations
+
+The scenario configuration UX will be expanded beyond `et-cli`. A Text User Interface (e.g. Ratatui) and a Graphical
+User Interface (e.g. eGUI) may be implemented in the future.
+
+The following future deployment types are also considered:
+
+- mprocs
+- nanocl
+- k3s
+- Rancher
+- OpenShift
+- Major cloud platforms: AWS, GCP, Azure
+
+## Consequences
+
+### Positive
+
+- Scenario definitions become much easier to read. A reviewer can understand the cluster intent from the YAML file
+  without reading the generated runtime files
+- Scenario authors can now define clusters with a compact YAML file instead of hand-coding deployment configuration
+- The same scenario definition can produce multiple operational formats, keeping cluster intent separate from runtime
+  mechanics
+- Verification scenarios are easier to add
+- Creates a clear extension point for future deployment types
+
+### Negative
+
+- The YAML schema becomes a new contract. When new features are added in the future, migration care is needed to
+  account for these changes.
+- Output types may not be behaviourally identical
+
+## Author
+
+Pierre Tenedero
+
+## Date
+
+28 April 2026