The central orchestration, API gateway, authentication, and container lifecycle service for running Artemis and Cuttlefish on Google Cloud Container-Optimized OS (COS).

📌 Core Responsibilities

Authentication & OTP Callbacks:
- Manages user verification (POST /api/v1/auth/otp/send and POST /api/v1/auth/otp/verify).
- Issues signed JWT access tokens for secure tenant separation.
- Provides session validation hooks for Nginx ingress (/api/v1/auth/validate-session).
Docker Socket Container Orchestration:
- Communicates with /var/run/docker.sock to dynamically spawn artemis-session-<session_id> containers on the shared artemis-net bridge network.
- Injects runtime environment variables (SESSION_ID, ADB_DEVICE_SERIAL, PORT=8080).
- Automatically executes adb connect inside the container to pair it with the Cuttlefish emulator.
Cloud Orchestrator & Cuttlefish Integration:
- Dispatches API requests to the Cloud Orchestrator service running on COS to spin up dedicated Cuttlefish AVDs.
- Binds allocated ADB ports (6520+N) and WebRTC signaling ports (8443+N).
BigQuery Mapping Store:
- Tracks metadata linking user_id, session_id, artemis_container_id, cuttlefish_adb_port, cuttlefish_webrtc_port, and timestamps.
- Includes automatic partitioned table creation on BigQuery (artemis_orchestration.sessions_registry) and an in-memory fallback for local dev.
Static Frontend UI Host:
- Serves the dual-pane web application (Cuttlefish WebRTC stream player + Artemis agent thought workspace) at /.
Automatic Session Reaper & Watchdog:
- Background periodic worker checks active sessions every 30s.
- Automatically destroys orphaned containers and AVDs when the session TTL expires or heartbeat fails.

📁 Directory Structure

playground/backend_manager/
├── Dockerfile                   # Python 3.12 slim image with health check
├── docker-compose.yml           # Compose spec with /var/run/docker.sock mount
├── requirements.txt             # FastAPI, Pydantic, Docker SDK, BigQuery, JWT
├── README.md                    # Detailed documentation
└── app/
    ├── main.py                  # FastAPI app entrypoint with lifespan manager
    ├── config.py                # Environment configuration settings
    ├── auth/
    │   ├── jwt_handler.py       # JWT encoding/decoding & get_current_user dependency
    │   └── otp_service.py       # OTP generation, storage, and verification
    ├── services/
    │   ├── docker_service.py    # Docker socket manager (start/stop containers)
    │   ├── cloud_orchestrator_service.py # Cloud Orchestrator Cuttlefish client
    │   ├── bigquery_service.py  # BigQuery mapping repository with local fallback
    │   └── session_manager.py   # Master session lifecycle & reaper coordinator
    ├── routers/
    │   ├── auth_router.py       # OTP and JWT endpoints
    │   ├── session_router.py    # Session creation, polling, heartbeat, and deletion
    │   └── health_router.py     # Liveness probe endpoint (/healthz)
    ├── schemas/
    │   ├── auth_schema.py       # Auth request/response schemas
    │   └── session_schema.py    # Session & mapping schemas
    └── static/
        ├── index.html           # Dual-pane glassmorphic web workspace
        ├── style.css            # Aurora design system styling
        └── app.js               # Frontend client logic & streaming hooks

🔌 REST API Endpoints

Authentication

POST /api/v1/auth/otp/send — Request a 6-digit OTP code ({"identifier": "user@example.com"}).
POST /api/v1/auth/otp/verify — Verify OTP code and receive signed JWT token ({"identifier": "...", "code": "123456"}).
GET /api/v1/auth/me — Return profile of the current authenticated user (Authorization: Bearer <jwt>).
GET /api/v1/auth/validate-session?session_id=... — Validate user authorization for a specific session.

Sessions & Container Management

POST /api/v1/sessions/create — Provision Cuttlefish AVD + Artemis container, link ADB, and register mapping.
GET /api/v1/sessions — List all active sessions for the current user.
GET /api/v1/sessions/{session_id} — Get session status and reverse-proxy stream endpoints.
POST /api/v1/sessions/{session_id}/heartbeat — Send client heartbeat to extend session TTL.
DELETE /api/v1/sessions/{session_id} — Terminate container and release Cuttlefish instance.

Health Probe

GET /healthz — Returns 200 OK with service health status.

⚙️ Environment Variables

Variable	Default	Description
`PORT`	`8000`	HTTP port to listen on
`APP_ENV`	`development`	Environment mode (`development` / `production`)
`JWT_SECRET_KEY`	`artemis-...`	Secret key for signing JWT session tokens
`DOCKER_SOCKET_PATH`	`unix://var/run/docker.sock`	Path to host Docker daemon socket
`DOCKER_NETWORK`	`artemis-net`	Shared bridge network for dynamic container routing
`ARTEMIS_IMAGE`	`artemis:latest`	Docker image to spawn for Artemis instances
`CLOUD_ORCHESTRATOR_URL`	`http://host.docker.internal:1443`	Endpoint of the Cloud Orchestrator service
`CUTTLEFISH_HOST_GATEWAY`	`host.docker.internal`	Host IP / gateway for ADB TCP connections
`GOOGLE_CLOUD_PROJECT`	`artemis-cloud-project`	GCP project ID for BigQuery dataset
`USE_LOCAL_FALLBACK_DB`	`true`	Enables in-memory DB fallback if BigQuery is unconfigured
`SESSION_TTL_MINUTES`	`60`	Default session lifespan before automatic teardown

🚀 Running the Container

1. Build Image

docker build -t artemis-backend-manager:latest .

2. Run with Docker Compose

docker-compose up -d

3. Run Standalone with Docker on COS

docker run -d \
  --name backend \
  --restart unless-stopped \
  --network artemis-net \
  --add-host host.docker.internal:host-gateway \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8000:8000 \
  artemis-backend-manager:latest