senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/docs/ONBOARDING.md

7.4 KiB
Raw Blame History

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

Quick start (minimal: Backend + Web)

# 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

Or step by step:

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

Full setup (with Chat + Stream servers)

Option A — Local Rust servers + Backend in Docker

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

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

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

Environment

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

# 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 — Tailwind, Storybook, layout
Design tokens apps/web/docs/DESIGN_TOKENS.md
Backend contributing veza-backend-api/CONTRIBUTING.md
Backend patterns veza-backend-api/README.md — core vs handlers
Storybook contract apps/web/docs/STORYBOOK_CONTRACT.md
Full layout page 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)

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)

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

6. Troubleshooting

Port 8080 already in use

Override ports in .env:

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:

docker compose -f docker-compose.yml ps

Rust servers fail to compile

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

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

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