Refactor code structure for improved readability and maintainability

deploy/compose/README.md

@@ -13,7 +13,10 @@ These Compose bundles ship the minimum services required to exercise the scanner
 | `docker-compose.mirror.yaml` | Managed mirror topology for `*.stella-ops.org` distribution (Concelier + Excititor + CDN gateway). |
 | `docker-compose.telemetry.yaml` | Optional OpenTelemetry collector overlay (mutual TLS, OTLP ingest endpoints). |
 | `docker-compose.telemetry-storage.yaml` | Prometheus/Tempo/Loki storage overlay with multi-tenant defaults. |
+| `docker-compose.gpu.yaml` | Optional GPU overlay enabling NVIDIA devices for Advisory AI web/worker. Apply with `-f docker-compose.<env>.yaml -f docker-compose.gpu.yaml`. |
 | `env/*.env.example` | Seed `.env` files that document required secrets and ports per profile. |
+| `scripts/backup.sh` | Pauses workers and creates tar.gz of Mongo/MinIO/Redis volumes (deterministic snapshot). |
+| `scripts/reset.sh` | Stops the stack and removes Mongo/MinIO/Redis volumes after explicit confirmation. |
 
 ## Usage
 
@@ -101,4 +104,18 @@ The Helm chart mirrors these settings under `services.advisory-ai-web` / `adviso
 2. Update image digests in the relevant Compose file(s).
 3. Re-run `docker compose config` to confirm the bundle is deterministic.
 
-Keep digests synchronized between Compose, Helm, and the release manifest to preserve reproducibility guarantees. `deploy/tools/validate-profiles.sh` performs a quick audit.
+Keep digests synchronized between Compose, Helm, and the release manifest to preserve reproducibility guarantees. `deploy/tools/validate-profiles.sh` performs a quick audit.
+
+### GPU toggle for Advisory AI
+
+GPU is disabled by default. To run inference on NVIDIA GPUs:
+
+```bash
+docker compose \
+  --env-file prod.env \
+  -f docker-compose.prod.yaml \
+  -f docker-compose.gpu.yaml \
+  up -d
+```
+
+The GPU overlay requests one GPU for `advisory-ai-worker` and `advisory-ai-web` and sets `ADVISORY_AI_INFERENCE_GPU=true`. Ensure the host has the NVIDIA container runtime and that the base compose file still sets the correct digests.

deploy/compose/docker-compose.gpu.yaml

@@ -0,0 +1,26 @@
+version: "3.9"
+
+services:
+  advisory-ai-worker:
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - capabilities: [gpu]
+              driver: nvidia
+              count: 1
+    environment:
+      ADVISORY_AI_INFERENCE_GPU: "true"
+    runtime: nvidia
+
+  advisory-ai-web:
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - capabilities: [gpu]
+              driver: nvidia
+              count: 1
+    environment:
+      ADVISORY_AI_INFERENCE_GPU: "true"
+    runtime: nvidia

deploy/compose/scripts/backup.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "StellaOps Compose Backup"
+echo "This will create a tar.gz of Mongo, MinIO (object-store), and Redis data volumes."
+read -rp "Proceed? [y/N] " ans
+[[ ${ans:-N} =~ ^[Yy]$ ]] || { echo "Aborted."; exit 1; }
+
+TS=$(date -u +%Y%m%dT%H%M%SZ)
+OUT_DIR=${BACKUP_DIR:-backups}
+mkdir -p "$OUT_DIR"
+
+docker compose ps >/dev/null
+
+echo "Pausing worker containers for consistency..."
+docker compose pause scanner-worker scheduler-worker taskrunner-worker || true
+
+echo "Backing up volumes..."
+docker run --rm \
+  -v stellaops-mongo:/data/db:ro \
+  -v stellaops-minio:/data/minio:ro \
+  -v stellaops-redis:/data/redis:ro \
+  -v "$PWD/$OUT_DIR":/out \
+  alpine sh -c "cd / && tar czf /out/stellaops-backup-$TS.tar.gz data"
+
+docker compose unpause scanner-worker scheduler-worker taskrunner-worker || true
+
+echo "Backup written to $OUT_DIR/stellaops-backup-$TS.tar.gz"

deploy/compose/scripts/reset.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "WARNING: This will stop the stack and wipe Mongo, MinIO, and Redis volumes."
+read -rp "Type 'RESET' to continue: " ans
+[[ ${ans:-} == "RESET" ]] || { echo "Aborted."; exit 1; }
+
+docker compose down
+
+for vol in stellaops-mongo stellaops-minio stellaops-redis; do
+  echo "Removing volume $vol"
+  docker volume rm "$vol" || true
+done
+
+echo "Reset complete. Re-run compose with your env file to recreate volumes."