# 📊 Veza Lab Environment Report

## Overview
We have successfully established a robust **Veza Lab Environment** orchestrated via a single command. This environment replicates the full production stack, including infrastructure, backend services, and a unified ingress gateway, all running locally for development and testing.

**Command to Start:**
```bash
make dev-lab
```

## 🏗️ Architecture

The Lab environment differs slightly from production to facilitate easy debugging (running apps on host) while keeping infrastructure isolated (in Docker).

```mermaid
graph TD
    User[User / Browser] -->|http://localhost:80| HAProxy(Docker: veza-lab-haproxy)
    
    subgraph "Docker Infrastructure (veza-lab-net)"
        Postgres[(Postgres 16)]
        Redis[(Redis 7)]
        RabbitMQ[(RabbitMQ 3)]
        HAProxy
    end
    
    subgraph "Host Machine (Mac/Linux)"
        HAProxy -->|Proxy| Backend[veza-backend-api :8080]
        HAProxy -->|Proxy| Chat[veza-chat-server :8081]
        HAProxy -->|Proxy| Stream[veza-stream-server :8082]
        HAProxy -->|Proxy| Web[apps/web :3000]
        
        Backend --> Postgres
        Chat --> Postgres
        Stream --> Postgres
        
        Backend --> Redis
        Chat --> Redis
        Stream --> Redis
        
        Chat --> RabbitMQ
    end
```

### Components

| Service | Port (Host) | DB Connection | Status |
|---------|-------------|---------------|--------|
| **HAProxy** | `:80` | N/A | ✅ Proxying to Host |
| **Backend API** | `:8080` | `veza_lab` | ✅ Healthy |
| **Chat Server** | `:8081` | `veza_chat` | ✅ Healthy |
| **Stream Server** | `:8082` | `veza_lab` | ✅ Healthy |
| **Frontend** | `:3000` | N/A | ✅ Fixed (QueryClient added) |
| **Postgres** | `:5432` | N/A | ✅ v16 |
| **Redis** | `:6379` | N/A | ✅ v7 |
| **RabbitMQ** | `:5672` | N/A | ✅ v3 + Mgmt |

## 🛠️ Implementation Details

### 1. Unified Orchestration (`make dev-lab`)
The `make dev-lab` command chains the following steps:
1.  **`infra-up`**: Starts Docker containers defined in `infra/docker-compose.lab.yml`.
    *   *Improvement*: Added **HAProxy** to this stack.
    *   *Feature*: Auto-creates databases (`veza_lab`, `veza_chat`, `veza_stream`) and installs required extensions (`uuid-ossp`, `pgcrypto`, `btree_gin`) on startup.
2.  **`infra-check`**: Validates that Postgres, Redis, RabbitMQ, and HAProxy are responsive.
3.  **`migrate-all`**: Runs migrations for all services.
    *   *Resolution*: Solved conflict between Chat and Stream migrations (both using `001_initial`) by isolating Chat to its own `veza_chat` database. Stream shares `veza_lab` with Backend to access core `tracks`.
4.  **`services-up`**: Launches Go, Rust, and Node.js applications in the background.
    *   *Fix*: Corrected log paths and removed cleanup traps so services persist after the script finishes.
5.  **`health-all`**: Polls health endpoints (`/health`, `/readyz`) to confirm startup.

### 2. HAProxy Integration
We added HAProxy to serve as the single entry point, mimicking production routing locally.
*   **Config**: `docker/haproxy/haproxy.lab.cfg`
*   **Routing**:
    *   `/api` -> Backend API
    *   `/ws/chat` -> Chat Server
    *   `/hls`, `/stream` -> Stream Server
    *   `*` -> Frontend (React App)
*   **Network Magic**: configured with `extra_hosts: host.docker.internal:host-gateway` to allow the Dockerized HAProxy to route traffic to apps running natively on your host machine.

### 3. Frontend Fixes
During verification, the frontend crashed with a `QueryClientProvider` error.
*   **Fix**: Modified `apps/web/src/main.tsx` to wrap the application in `<QueryClientProvider>`, ensuring React Query functions correctly.

## ✅ Verification Status

*   **Infrastructure**: All containers up.
*   **Migrations**: All applied successfully (idempotent).
*   **Services**: All processes running and reachable.
*   **Frontend**: Loads via `http://localhost`.

## ⏭️ Next Steps
*   **Development**: You can now edit code in `apps/web` or any backend service; the changes will reflect (for web/Go via live reload if configured, or restart for Rust).
*   **Shutdown**: Currently, services run in background. Use `pkill -f veza` or kill ports to stop host apps. `docker compose -f infra/docker-compose.lab.yml down` stops infra.