fx-test/docs/architecture.md

🏗️ 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.