veza/docs/ONBOARDING.md

# Developer Onboarding Guide — Veza Monorepo

This guide helps new developers set up the Veza monorepo and understand its architecture, conventions, and workflows.

---

## 1. Prerequisites

| Tool | Version | Purpose |
|------|---------|---------|
| **Node.js** | 18+ | Frontend (React, Vite) |
| **Go** | 1.23+ | Backend API |
| **Rust** | 2021 edition | Chat server, Stream server |
| **Docker** | 24+ | PostgreSQL, Redis, RabbitMQ, ClamAV, Backend, Chat, Stream |
| **PostgreSQL** | 12+ | Primary database |
| **Redis** | 7+ | Cache, sessions, rate limiting |
| **RabbitMQ** | 3+ | Async events |
| **Git** | 2.30+ | Version control |
| **Make** | GNU Make | Build automation |

### Optional (for hot reload)

- **air** — Go hot reload: `go install github.com/air-verse/air@latest`
- **cargo-watch** — Rust hot reload: `cargo install cargo-watch`

---

## 2. Setup in 5 Minutes (target: <30 min clone → first test passing)

### Quick start (minimal: Backend + Web)

```bash
# 1. Clone the repo
git clone https://github.com/veza/veza.git
cd veza

# 2. First-time setup: install deps + start infra + run migrations
make setup-dev

# 3. Start backend + web (frontend)
make dev
```

### Verify your setup (<30 min total)

Run these commands to confirm everything works:

```bash
# Backend tests (from repo root)
make test-backend-api

# Frontend tests
make test-web
```

If both pass, your environment is ready. Troubleshooting: see [§6](#6-troubleshooting).

Or step by step:

```bash
make setup        # Install dependencies (Go, Rust, npm)
make infra-up     # Start PostgreSQL, Redis, RabbitMQ
make db-migrate   # Run migrations
make dev          # Start backend + web
```

- **Backend API**: http://veza.fr:18080 (or http://localhost:18080)
- **Web**: http://veza.fr:5173 (or http://localhost:5173)

### Full setup (with Chat + Stream servers)

**Option A — Local Rust servers + Backend in Docker**

```bash
make infra-up
make db-migrate
make dev-full
```

**Option B — Full stack v0.101 (all services in Docker)**

```bash
make infra-up     # Starts Postgres, Redis, RabbitMQ, ClamAV, Backend, Chat, Stream
make db-migrate   # Run migrations
make dev-web      # Start frontend locally (Vite)
```

- **Backend API**: http://localhost:18080
- **Chat Server**: http://localhost:18081 (WebSocket)
- **Stream Server**: http://localhost:18082 (HLS)
- **Web**: http://localhost:5173

### Environment

Create `veza/.env` to override defaults (see `make/config.mk`):

```bash
# Example overrides
APP_DOMAIN=localhost
PORT_backend-api=8080
PORT_web=5173
DB_USER=veza
DB_PASS=your-secure-password
DB_PORT=15432
```

Backend-specific env: copy `veza-backend-api/.env.example` to `veza-backend-api/.env` and set:

- `DATABASE_URL` — PostgreSQL connection string
- `JWT_SECRET` — min 32 characters
- `APP_ENV` — `development`, `staging`, or `production`

---

## 3. Architecture

### Data flow

```
Browser → HAProxy (port 80/443) [prod] or direct (dev)
  ├── /api/* → Backend Go (port 8080)
  │     ├── PostgreSQL (port 5432) — main data
  │     ├── Redis (port 6379) — sessions, cache, rate limiting
  │     ├── RabbitMQ (port 5672) — async events
  │     └── ClamAV (port 3310) — virus scanning
  ├── /ws → Chat Server Rust (port 3000)
  │     ├── PostgreSQL — messages
  │     └── Redis — pub/sub, rate limiting
  ├── /stream → Stream Server Rust (port 3001)
  │     ├── PostgreSQL — metadata
  │     └── Redis — cache
  └── /* → Frontend SPA (port 5173)
```

### Project structure

```
veza/
├── apps/web/                  # React + Vite frontend (single source of truth for UI)
├── veza-backend-api/          # Go API (Gin, GORM)
├── veza-chat-server/           # Rust WebSocket chat
├── veza-stream-server/         # Rust audio streaming (HLS, WebRTC)
├── veza-common/               # Shared Rust library
├── packages/                  # NPM shared packages
├── config/                    # HAProxy, Prometheus
├── k8s/                       # Kubernetes manifests
├── migrations/                # SQL migrations
├── loadtests/                 # k6 load tests
├── make/                      # Makefile modules
└── docs/                      # Documentation
```

---

## 4. Conventions

| Resource | Location |
|----------|----------|
| **UI rules** | [.cursorrules](.cursorrules) — Tailwind, Storybook, layout |
| **Design tokens** | [apps/web/docs/DESIGN_TOKENS.md](apps/web/docs/DESIGN_TOKENS.md) |
| **Backend contributing** | [veza-backend-api/CONTRIBUTING.md](veza-backend-api/CONTRIBUTING.md) |
| **Backend patterns** | [veza-backend-api/README.md](veza-backend-api/README.md) — core vs handlers |
| **Storybook contract** | [apps/web/docs/STORYBOOK_CONTRACT.md](apps/web/docs/STORYBOOK_CONTRACT.md) |
| **Full layout page** | [apps/web/docs/FULL_LAYOUT_PAGE.md](apps/web/docs/FULL_LAYOUT_PAGE.md) |

---

## 5. Useful Commands

### From repo root

| Command | Description |
|---------|-------------|
| `make help` | Show all targets |
| `make infra-up` | Start Docker infra (Postgres, Redis, RabbitMQ) |
| `make infra-down` | Stop infra |
| `make db-migrate` | Run migrations |
| `make dev` | Backend + Web (no Chat/Stream) |
| `make dev-full` | All services |
| `make dev-web` | Web only |
| `make dev-backend-api` | Go backend only |
| `make test` | Run all tests |
| `make test-web` | Test frontend only |
| `make test-backend-api` | Test backend only |
| `make lint` | Lint everything |
| `make load-test-smoke` | k6 smoke test |

### Per service

| Service | Build | Test | Lint |
|---------|-------|------|------|
| Web | `make build-web` | `make test-web` | `make lint-web` |
| Backend API | `make build-backend-api` | `make test-backend-api` | `make lint-backend-api` |
| Chat Server | `make build-chat-server` | `make test-chat-server` | `make lint-chat-server` |
| Stream Server | `make build-stream-server` | `make test-stream-server` | `make lint-stream-server` |

### Frontend (from apps/web)

```bash
cd apps/web
npm run dev          # Dev server
npm run build        # Production build
npm run test -- --run
npm run lint
npm run storybook    # UI docs
npm run visual:capture
npm run visual:compare
```

### Backend (from veza-backend-api)

```bash
cd veza-backend-api
go build ./...
go test ./... -short
make lint
```

---

## 6. Troubleshooting

### Port 8080 already in use

Override ports in `.env`:

```bash
PORT_backend-api=18080
PORT_web=5173
```

### Database connection refused

1. Ensure infra is up: `make infra-up`
2. Check `DATABASE_URL` in `veza-backend-api/.env` and use host `localhost` with port `15432` (or `DB_PORT` from config)
3. Ensure ports match: `make/config.mk` uses `PORT_POSTGRES ?= 15432`

### Redis / RabbitMQ unavailable

`make infra-up` starts Postgres, Redis, RabbitMQ. If one fails, check:

```bash
docker compose -f docker-compose.yml ps
```

### Rust servers fail to compile

```bash
cd veza-chat-server && cargo build --release
cd veza-stream-server && cargo build --release
```

If `veza-common` has issues, ensure it's built first:

```bash
cd veza-common && cargo build
```

### Frontend tests fail

- Ensure MSW is not blocking: `VITE_USE_MSW=0` by default
- Run with `npm run test -- --run` from `apps/web/`

### Migrations fail

- Backend: `cd veza-backend-api && go run cmd/migrate_tool/main.go up`
- Chat: `cd veza-chat-server && sqlx migrate run`
- Stream: `cd veza-stream-server && sqlx migrate run`

---

## See also

- [README](../README.md) — Quick start
- [veza-backend-api/README.md](../veza-backend-api/README.md) — API structure
- [loadtests/README.md](../loadtests/README.md) — Load testing
- [archive/AUDIT_TECHNIQUE_INTEGRAL_2026_02_15.md](archive/AUDIT_TECHNIQUE_INTEGRAL_2026_02_15.md) — Technical audit