Add comprehensive documentation for fx-test repo

docs/architecture.md

@@ -0,0 +1,45 @@
+# 🏗️ Architecture Overview
+
+The **fx-test** repository is a lightweight implementation of a service stack built on top of a multi‑host Docker environment. It mirrors key aspects of the larger `homelab` infrastructure but is intentionally simplified for testing, CI/push pipelines, or educational purposes.
+
+## 1️⃣ Core Components
+
+| Component | Role | Deployment Method |
+|-----------|------|-------------------|
+| **Fluxer Relay** | Acts as a messaging layer between services, handling websockets and HTTP requests. | Docker stack deployed on the `flasher` cluster.
+| **CI Workflows** | Automate validation, tests, and deployments. | GitHub Actions or local `./scripts/run_dev.sh`.
+| **Ethical Gateway** | Provides a secure entry point to services using OAuth2/JWT based auth. | Docker container bundled in the stack.
+
+## 2️⃣ Service Architecture
+
+```
+┌─────────────────────┐
+│    Fluxer Relay      │
+└─────────────┬───────┘
+              │
+┌─────────────▼───────┐
+│  CI Pipeline Scripts │
+└─────────────────────┘
+```
+
+The **Fluxer Relay** exposes two major APIs:
+
+* **WS API** – Real‑time communication, used by front‑end clients.
+* **HTTP API** – CRUD endpoints for configuration and statistics.
+
+The CI scripts orchestrate the following steps when a push is received:
+1. **Lint** – Run `molecule lint` and `dialyzer` on Erlang modules.
+2. **Compile** – Compile Erlang/Elixir modules and generate release artifacts.
+3. **Test** – Execute unit tests, integration tests, and benchmarks.
+4. **Package** – Build Docker images and push to internal registry.
+5. **Deploy** – Trigger a GitOps redeploy using Portainer API.
+
+## 3️⃣ Deployment Flow
+
+1. **Push** – Code changes are pushed to `main` or a feature branch.
+2. **CI** – The Git Actions runner (or local CI) runs the pipeline.
+3. **Container Image Build** – A new Docker image is produced.
+4. **Portainer Sync** – The new image is pulled by Portainer, stack updated.
+5. **Health Check** – Automated health probes ensure services are up.
+
+> **Note:** The repository’s `fluxer-seattle` folder holds the `Dockerfile` and `rebar config` for building the `fluxer` binary.