WAIIDE Architecture

Calliope Integration: This component is integrated into the Calliope AI platform. Some features and configurations may differ from the upstream project.

Understanding WAIIDE’s architecture helps with configuration, troubleshooting, and custom integrations.

🏗️ System Overview

• Architecture Overview - Complete system design and components
• Services and Ports - Service interactions and networking
• Integration Patterns - How WAIIDE integrates with JupyterHub

🔧 Core Components

WAIIDE Container Architecture

┌─────────────────────────────────┐
│     WAIIDE Container            │
│                                 │
│  ┌─────────────────────────┐    │
│  │  Entrypoint Script      │    │
│  │  - Environment Detection│    │
│  │  - Permission Management│    │  
│  │  - Service Orchestration│    │
│  └─────────────────────────┘    │
│                                 │
│  ┌─────────────────────────┐    │
│  │  JupyterHub Mode        │    │
│  │  ├─ jupyterhub-singleuser  │
│  │  ├─ jupyter-server-proxy│    │
│  │  └─ WAIIDE (port 8071) │    │
│  └─────────────────────────┘    │
│                                 │
│  ┌─────────────────────────┐    │
│  │  Standalone Mode        │    │
│  │  ├─ API Server (8080)   │    │
│  │  └─ WAIIDE (port 8071) │    │
│  └─────────────────────────┘    │
└─────────────────────────────────┘

Service Discovery and Health Checking

• API Endpoints: /api, /api/status, /api/services
• Health Checks: JupyterHub compatibility
• Service Registry: Dynamic service detection

🌐 Network Architecture

Port Configuration

URL Routing (JupyterHub Mode)

External Request: /user/lmata/lmata-waiide-abc123/
                ↓
JupyterHub Proxy: Routes to container
                ↓
jupyterhub-singleuser: Port 8080
                ↓
jupyter-server-proxy: Detects WAIIDE
                ↓
WAIIDE Server: Port 8071 (internal)
                ↓
Response: WAIIDE UI at root path

URL Routing (Standalone Mode)

External Request: http://localhost:8080/
                ↓
API Server: Port 8080
                ↓
Proxy Logic: Routes to WAIIDE
                ↓
WAIIDE Server: Port 8071 (internal)
                ↓  
Response: WAIIDE UI with path rewriting

🔄 Multi-Instance Architecture

Instance Isolation

• Container Per Instance: Each server gets its own container
• Unique Naming: username-service-hash format ensures no conflicts
• Resource Isolation: CPU, memory, and storage per instance
• Network Isolation: Each container has its own network namespace

Instance Management

User: lmata

Instance 1: lmata-waiide-abc123
├─ Container: lmata-waiide-abc123
├─ URL: /user/lmata/lmata-waiide-abc123/
└─ Storage: volume-lmata-waiide-abc123

Instance 2: lmata-lab-def456  
├─ Container: lmata-lab-def456
├─ URL: /user/lmata/lmata-lab-def456/
└─ Storage: volume-lmata-lab-def456

🔐 Authentication and Security

OAuth Flow

1. User Access: User visits instance URL
2. JupyterHub Auth: Validates user session
3. OAuth Token: JupyterHub provides API token
4. Container Auth: Token validated for container access
5. WAIIDE Access: User authenticated to WAIIDE

Security Boundaries

• User Isolation: Each user’s containers run as UID 1000
• Network Security: WAIIDE only accessible via proxy
• Token Security: OAuth tokens are scoped per instance
• File System: User home directories are isolated

📊 Data Flow

Request Processing

1. User Request → JupyterHub Proxy
2. Proxy → Container (port 8080)
3. Container → jupyterhub-singleuser
4. singleuser → jupyter-server-proxy  
5. proxy → WAIIDE Server (port 8071)
6. WAIIDE → Response
7. Response → User (with URL rewriting)

WebSocket Handling

• Upgrade Detection: Automatic WebSocket upgrade handling
• Bidirectional Proxy: Full duplex communication
• Connection Management: Proper connection lifecycle
• Error Handling: Graceful disconnection handling

⚙️ Configuration Integration

Environment-Based Configuration

• JupyterHub Mode: Detected via JUPYTERHUB_* variables
• Instance Names: Read from JUPYTERHUB_SERVER_NAME
• URL Prefixes: Applied from JUPYTERHUB_SERVICE_PREFIX
• Dynamic Config: Configuration adapts to environment

Container Lifecycle

1. Container Start → Root privileges
2. Permission Fix → Set ownership to 1000:100
3. User Drop → Switch to UID 1000
4. Environment Check → Detect JupyterHub mode
5. Service Start → Launch appropriate services
6. Health Check → Report ready status

🔌 Extension Points

Custom Spawners

• ECS Integration: Environment variable passing
• Kubernetes: Pod specification
• Custom Spawners: Generic integration pattern

Service Discovery

• API Endpoints: Programmatic service discovery
• Health Monitoring: Integration with monitoring systems
• Load Balancing: Multiple instance coordination

📈 Performance Characteristics

Resource Usage

• Base Memory: ~500MB per container
• CPU Usage: Variable based on WAIIDE usage
• Storage: User workspace + WAIIDE extensions
• Network: Minimal overhead from proxying

Scaling Patterns

• Horizontal: Multiple instances per user
• Vertical: Resource limits per container
• Auto-scaling: Based on resource usage
• Load Distribution: Across multiple nodes

🔍 Monitoring and Observability

Built-in Monitoring

• Health Endpoints: /api/status, /api/services
• Log Aggregation: Structured logging
• Metrics: Service availability and performance
• Debugging: Detailed error reporting

Integration Points

• Prometheus: Metrics exposition
• Grafana: Dashboard integration
• ELK Stack: Log analysis
• Custom Monitoring: API-based monitoring

📖 Related Documentation

• Configuration - How to configure this architecture
• Troubleshooting - Fix architectural issues
• Development - Extend the architecture

💡 Next Steps: Review Configuration to implement this architecture!