diff --git a/docs/INDEX.md b/docs/INDEX.md
new file mode 100644
index 00000000..0efd747a
--- /dev/null
+++ b/docs/INDEX.md
@@ -0,0 +1,18 @@
+# 📘 Repository Documentation Index
+
+Welcome to the comprehensive documentation for the **fx-test** repository. This guide serves as a centralized navigation hub, directing users to the various sections of documentation relevant to the project.
+
+---
+
+## 📁 Documentation Sections
+
+- **[Architecture Overview](/docs/architecture.md)** – Understand the system architecture, key components, and deployment strategy.
+- **[Quick Start](/docs/quickstart.md)** – Deploy and run the service Stack in minutes.
+- **[Usage Guide](/docs/usage.md)** – Detailed instructions for interacting with the services.
+- **[Configuration](/docs/configuration.md)** – Environment variables, defaults, and service-specific options.
+- **[Troubleshooting](/docs/troubleshooting.md)** – Common issues and how to resolve them.
+- **[Contribution](/docs/contributing.md)** – Guidelines for contributing to the repository.
+
+---
+
+For technical details, each README in a sub‑module and the CI/CD scripts contain inline comments that further aid developers.
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 00000000..f936b7a9
--- /dev/null
+++ b/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.
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 00000000..60e068bc
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,12 @@
+# 🤝 Contributing Guidelines
+
+We welcome contributions! Please follow these steps:
+
+1. **Fork** the repository.
+2. Create a feature branch: `git checkout -b feature/awesome-feature`.
+3. Implement your change locally and run `./fluxer/scripts/run_dev.sh` to ensure the stack builds.
+4. Run the CI tests: `./fluxer/scripts/ci/workflows/ci.py`.
+5. Commit with a clear message: `git commit -m "Add feature: …"`.
+6. Push and open a pull request.
+
+Adhere to the existing code style. All patches should include relevant tests.
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 00000000..5fe0b455
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,60 @@
+# 🚀 Quick Start Guide
+
+Follow this step‑by‑step guide to spin up the **fx-test** service stack locally. The instructions assume you have Docker, Docker‑Compose, and Git installed.
+
+## 1️⃣ Clone the Repository
+
+```bash
+git clone https://git.vish.gg/Vish/fx-test.git
+cd fx-test
+```
+
+## 2️⃣ Build & Deploy
+
+The repository uses Docker‑Compose stacks wrapped in a **GitOps** pattern. The simplest way to start the stack locally is with the provided `run_dev.sh` script.
+
+```bash
+./fluxer/scripts/run_dev.sh
+```
+
+* The script pulls the latest code, compiles the Erlang project, builds the Docker image, and spins up the stack via `docker-compose`.
+
+## 3️⃣ Verify the Service
+
+Once the containers are running, you can verify the API endpoints:
+
+```bash
+# Port 8080 – WS API
+curl http://localhost:8080
+# Port 8090 – HTTP API
+curl http://localhost:8090/health
+```
+
+Both should respond with JSON payloads confirming the service is healthy.
+
+## 4️⃣ Interacting with the WebSocket
+
+Use `wscat` (or any `ws` client) to open a connection:
+
+```bash
+npm install -g wscat
+wscat -c ws://localhost:8080
+```
+
+Send a simple test message:
+
+```json
+{"type":"ping"}
+```
+
+You'll receive a `pong` response if the relay is working.
+
+---
+
+### Troubleshooting Tips
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Containers exit instantly | Build step failed | Check CI logs, rebuild locally with `make` |
+| HTTP endpoints return **503** | Health check script misconfigured | Verify `/fluxer/config/health_check.json` |
+| WebSocket not reachable | Port blocked | Ensure OS firewall allows 8080 |
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 00000000..66bbbcd8
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,69 @@
+# 📖 Usage Guide
+
+The **fx-test** stack exposes two primary interfaces:
+
+1. **WebSocket** – Real‑time event channel.
+2. **HTTP** – RESTful configuration and monitoring.
+
+## 1️⃣ WebSocket API
+
+The WebSocket endpoint is available on port `8080`. Common message types:
+
+| Message Type | Description |
+|--------------|-------------|
+| `ping` | Health check; server replies with `pong`. |
+| `subscribe` | Subscribe to a topic; server sends updates. |
+| `publish` | Broadcast a message to all clients. |
+
+Example using Node.js:
+
+```js
+const ws = require("ws");
+const socket = new ws("ws://localhost:8080");
+
+socket.on("open", () => socket.send(JSON.stringify({type:"ping"}));
+
+socket.on("message", m => console.log("Received: ", m));
+```
+
+## 2️⃣ HTTP API
+
+### Health
+
+```bash
+GET /health
+```
+
+Response:
+```json
+{"status":"ok","uptime":123456}
+```
+
+### Status
+
+```bash
+GET /status
+```
+
+Returns the current number of connected WebSocket clients and processing metrics.
+
+## 3️⃣ Configuring via ENV
+
+The stack reads the following environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| **PORT** | `8080` | WebSocket port |
+| **HTTP_PORT** | `8090` | HTTP listening port |
+| **REGISTRY** | `docker.io` | Registry to fetch Docker images |
+| **DEBUG** | `false` | Enable debug logging |
+
+Set the environment variables in a `.env` file at the repo root or export them in your shell before running `run_dev.sh`.
+
+---
+
+## 4️⃣ Extending the Stack
+
+1. **Add a new service** – Place a `Dockerfile` in `fluxer/` and reference it in the `docker-compose.yml`.
+2. **Modify the relay** – Edit the Erlang source in `fluxer_relay/src/relay/`. After editing, recompile with `rebar3 do compile, release` and rebuild the Docker image.
+3. **Update the CI** – Extend `ci/workflows/**.py` to run any new tests.