docs: add developer onboarding guide
This commit is contained in:
senke
parent
45008a4c21
commit
36c03e1cba
3 changed files with 255 additions and 3 deletions
|
|
@ -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/`.
|
||||
|
|
|
|||
247
docs/ONBOARDING.md
Normal file
247
docs/ONBOARDING.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue