From 0ea5373390b489eb2bd06a28340c41d4d555710a Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Tue, 10 Mar 2026 17:50:55 -0400
Subject: [PATCH] docs: clarify traffic architecture and ae_app vs ae_api
 scaling options

---
 CHEATSHEET.md | 29 ++++++++++++++++++++++++++++-
 README.md     | 32 ++++++++++++++++++++++++++++++--
 2 files changed, 58 insertions(+), 3 deletions(-)

diff --git a/CHEATSHEET.md b/CHEATSHEET.md
index 894e385..3f5345f 100644
--- a/CHEATSHEET.md
+++ b/CHEATSHEET.md
@@ -19,9 +19,36 @@
 - **Automated Import:** Drop file in `backups/import/` -> Run `./check_and_import.sh`.
 
 ## 📈 Scaling
-1. Edit `.env` -> `AE_API_REPLICAS=X` (or `AE_APP_REPLICAS=X`)
+
+### ae_api — scales via Docker DNS (no host ports needed)
+`ae_api` has no host ports. External traffic enters via `ae_web_dev` (port 5060/443),
+which round-robins across all `ae_api` replicas using Docker's internal DNS.
+
+1. Edit `.env` → `AE_API_REPLICAS=X`
 2. Run `docker compose up -d`
 
+No home-server nginx changes needed.
+
+### ae_app — two scaling options
+
+**Option A (recommended): Route through ae_web_dev (same as ae_api)**
+- Home server nginx points `dev-*.oneskyit.com` at `workstation:443`
+- ae_web_dev round-robins to `ae_app` replicas via Docker DNS
+- No host ports needed on ae_app, no home nginx changes when scaling
+- Same topology as ae_api
+
+**Option B (current): Direct host port binding**
+- Home server nginx points at `workstation:3001`, `3002`, etc.
+- `AE_APP_NODE_PORT_RANGE=3001-3006` in `.env`; Docker assigns one port per replica
+- Must uncomment matching entries in home server nginx upstream when adding replicas
+- Maximum 6 replicas without changing the range
+
+To scale with Option B:
+1. Edit `.env` → `AE_APP_REPLICAS=X` (max 6 with current range)
+2. Run `docker compose up -d ae_app`
+3. Uncomment matching port entries in home server nginx upstream
+4. Reload home server nginx
+
 ## 🧹 Maintenance
 - **Internal Logs:** Docker handles rotation automatically (10MB limit).
 - **External Proxy:** Point your home server to `[Workstation_IP]:5060`.
diff --git a/README.md b/README.md
index 06b528e..91ee6e8 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,34 @@
 
 This repository provides the unified Docker orchestration and configuration for the Aether Platform. It manages the lifecycle of the Aether API (FastAPI), Aether App (SvelteKit), and supporting infrastructure (MariaDB, Redis, Nginx).
 
+## 🌐 Traffic Architecture
+
+Understanding this prevents configuration mistakes.
+
+```
+External Internet
+      ↓
+Home Server Nginx (reverse proxy)
+      ↓                          ↓
+workstation:443            workstation:5060
+(ae_web_dev HTTPS)         (ae_web_dev API gateway)
+      ↓                          ↓
+  svelte_backend           fastapi_backend
+  (Docker DNS)             (Docker DNS)
+      ↓                          ↓
+ ae_app replicas          ae_api replicas
+ (round-robin)            (round-robin)
+```
+
+**Both ae_app and ae_api can scale via Docker DNS round-robin** when home server
+nginx routes through `ae_web_dev`. This is the recommended topology.
+
+Alternatively, ae_app can be reached directly via host port range (`3001-3006`),
+but this requires manually updating the home server nginx upstream for each replica.
+See the Scaling section in CHEATSHEET.md.
+
+---
+
 ## 🚀 Quick Start
 
 ### 1. Initialize Directory Structure
@@ -18,7 +46,7 @@ Copy the template and update it with your local paths and credentials:
 cd /srv/env/aether/container_env
 cp env.default .env
 # Edit .env to match your host system (Paths, DB, Ports)
-vim .env 
+vim .env
 ```
 
 ### 3. Configure Data & Source Paths
@@ -66,7 +94,7 @@ These scripts are located in the root directory:
 
 *   **`./backup_db.sh`**: Triggers an immediate hot backup. Results are stored in `backups/`.
 *   **`./export_db.sh`**: Creates a "Conference Ready" backup in `backups/conference_export/` with host-user ownership.
-*   **`./restore_db.sh [backup_file.gz]`**: Performs a full "Clean Slate" restoration. 
+*   **`./restore_db.sh [backup_file.gz]`**: Performs a full "Clean Slate" restoration.
     *   *Warning:* This stops MariaDB, archives current data, and resets `root` passwords to match your `.env`.
 *   **`./check_and_import.sh`**: A watchdog script that monitors `backups/import/` for new snapshots and triggers automated restoration.