# Project: Unified Aether Platform Orchestration (V3)
> **Goal:** Consolidate the SvelteKit Frontend and FastAPI Backend into a single Docker Compose environment within `aether_container_env`.

## 1. Overview & Benefits
Currently, the platform runs in two separate Docker environments (`ae_env_node_app` and `aether_container_env`). Combining them into one allows for:
- **Unified Lifecycle:** Start/Stop/Update the entire stack with one command.
- **Internal Networking:** The Frontend (SvelteKit) can communicate with the Backend (FastAPI) via the high-speed internal Docker network (`ae_api:5005`) instead of routing through external IPs.
- **Shared Infrastructure:** Single instances of Redis, Dozzle, and Nginx serving both tiers.
- **Simplified Deployment:** Reduces the need for sibling directory dependencies on production servers.

---

## 2. Target Architecture (Workstation & Prod)
The unified environment will reside in `~/OSIT_dev/aether_container_env/`.

### Directory Mapping
- **API Source:** `~/OSIT_dev/aether_api_fastapi` -> Mounted to `ae_api`
- **App Source:** `~/OSIT_dev/aether_app_sveltekit` -> Mounted to `ae_app`
- **Nginx Config:** `~/OSIT_dev/aether_container_env/conf/nginx/`
- **Logs:** `~/OSIT_dev/aether_container_env/logs/`

---

## 3. Implementation Plan

### Step 1: Update `aether_container_env/.env`
Add these new variables to the master `.env` file:
```bash
# --- SvelteKit Frontend settings ---
AE_APP_SRC=/home/scott/OSIT_dev/aether_app_sveltekit
CONTAINER_AE_APP=ae_app_dev
AE_APP_REPLICAS=4
AE_APP_NODE_PORT=3001
# Note: Use internal DNS 'ae_api' for PUBLIC_AE_API_SERVER_INTERNAL
```

### Step 2: Integrate `ae_app` into `docker-compose.yml`
Add the consolidated SvelteKit service. This replaces the legacy Flask service:
```yaml
    ae_app:
        restart: always
        build:
            context: ${AE_APP_SRC}
            dockerfile: Dockerfile
            target: deploy-node
        scale: ${AE_APP_REPLICAS}
        env_file:
            - ./.env
        ports:
            - "${AE_APP_NODE_PORT}:3000"
        extra_hosts:
            - "${DOCKER_AE_SERVER_EXTRA_HOST}"
            - "${DOCKER_AE_APP_SERVER_EXTRA_HOST}"
            - "${DOCKER_AE_API_SERVER_EXTRA_HOST}"
        volumes:
            # Mount source for real-time dev (Optional for production)
            - ${AE_APP_SRC}:/srv/aether_app
            - ${HOSTED_FILES_SRC}:/srv/hosted_files
            - ${HOSTED_TMP_SRC}:/srv/hosted_tmp
        depends_on:
            - ae_api
            - redis
        logging:
            driver: "json-file"
            options:
                max-size: "10m"
                max-file: "3"
```

### Step 3: Nginx Gateway Configuration
Update (or create) the Nginx template in `conf/nginx/` to route traffic to the internal `ae_app` service.

**Example Upstream Block:**
```nginx
upstream svelte_backend {
    # Internal Docker DNS handles load balancing across replicas
    server ae_app:3000;
    # ip_hash; # Enable if session persistence is needed
}
```

### Step 4: Verification & Migration
1. **Healthcheck:** Ensure `src/routes/health/+server.ts` is active.
2. **Internal Proxy Test:** Update SvelteKit's `PUBLIC_AE_API_SERVER` to `ae_api` (internal) and verify connectivity.
3. **Clean Up:** Once verified, the old `ae_env_node_app` directory can be archived.

---

## 4. Scaling & Performance
- **API Scaling:** Controlled by `AE_API_REPLICAS`.
- **App Scaling:** Controlled by `AE_APP_REPLICAS`.
- **Memory Management:** Each replica is isolated. Shared state (caching) is handled via the internal **Redis** service.
- **Healthchecks:** Docker will automatically restart any `ae_app` replica that fails the `/health` check.

---

## 5. Deployment Commands (Unified)
```bash
# From aether_container_env/
docker compose up -d --build --remove-orphans
docker compose ps
docker compose logs -f ae_app
```