diff --git a/README.md b/README.md index 3bf253a56..556a48de2 100644 --- a/README.md +++ b/README.md @@ -40,4 +40,6 @@ docker compose -f docker-compose.prod.yml up -d See `make/config.mk` for COMPOSE_PROD and deployment docs. ## Documentation -See `docs/` for detailed architecture and development guides. Older audits and reports are archived in `docs/archive/`. + +- **[Developer Onboarding](docs/ONBOARDING.md)** — Setup, architecture, conventions, troubleshooting +- See `docs/` for detailed architecture and development guides. Older audits and reports are archived in `docs/archive/`. diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md new file mode 100644 index 000000000..3b0ac78a0 --- /dev/null +++ b/docs/ONBOARDING.md @@ -0,0 +1,247 @@ +# 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 | +| **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) + +```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 +``` + +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) + +```bash +make infra-up +make db-migrate +make dev-full +``` + +### 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) + ├── /api/* → Backend Go (port 8080) + │ ├── PostgreSQL (port 5432) — main data + │ ├── Redis (port 6379) — sessions, cache, rate limiting + │ └── RabbitMQ (port 5672) — async events + ├── /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 +- [AUDIT_TECHNIQUE_INTEGRAL_2026_02_15.md](../AUDIT_TECHNIQUE_INTEGRAL_2026_02_15.md) — Technical audit diff --git a/make/high.mk b/make/high.mk index e9b0c3aa8..8da4b2a5e 100644 --- a/make/high.mk +++ b/make/high.mk @@ -5,8 +5,11 @@ .PHONY: setup stop-all restart-all clean clean-deep deploy-docker deploy-incus status-full .PHONY: web-minimal stop-minimal -setup: check-tools install-tools install-deps ## [HIGH] Full project initialization - @$(ECHO_CMD) "${BOLD}${GREEN}✅ Setup Complete! Ready to rock with 'make dev'.${NC}" +setup: check-tools install-tools install-deps ## [HIGH] Full project initialization (deps only) + @$(ECHO_CMD) "${BOLD}${GREEN}✅ Setup Complete! Run 'make setup-dev' for infra + migrations, then 'make dev'.${NC}" + +setup-dev: setup infra-up db-migrate ## [HIGH] First-time dev setup: deps + infra + migrations + @$(ECHO_CMD) "${BOLD}${GREEN}✅ Dev environment ready! Run 'make dev' to start.${NC}" web-minimal: ## [HIGH] Start Veza Web Minimal Journey (Backend + Frontend + DB) @$(SCRIPTS)/start_minimal.sh