Prerequisites

• Go 1.26+ (zyra-api) and Go 1.25+ (ws, notifications) · Node.js 20+ · Docker Desktop
• gcloud CLI with an @hpktechnology.com account (only needed to reach prod DB)
• Ask the team for each repo's .env — they are not in git

How the team actually runs it

Docker runs only the infra that is painful natively (LiveKit + Redis); app/api/ws run natively so hot-reload works.

# 1) infra: LiveKit SFU + Redis
docker compose up -d

# 2) one terminal each
cd zyra-api && go run .            # :3002  (or `air` for hot reload)
cd zyra-ws  && go run main.go      # :3003
cd zyra-notifications && go run .  # :3004
cd zyra-app && npm install && npm run dev   # :3000 (Turbopack)

Want the backend containerised instead? docker compose --profile backend up -d --build — native and container cannot share a port, so stop one side first.

Env vars that matter

Migrations

zyra-api only bootstraps the 10 core tables on start (inline DDL in internal/database/postgres.go). Files in zyra-api/migrations/*.sql are not auto-run — apply them by hand with psql.

app/                route exports only — no JSX, no state in here
views/<feature>/    the real UI: hero-<feature>.tsx (top level) + components/
components/         cross-feature reuse (admin/admin-sidebar.tsx, app-navbar, auth-guard)
lib/api/            REST calls — /api/user/* strictly separate from /api/admin/*
lib/auth/           session.ts · register.ts · forgot-password.ts
stores/             Zustand + Dexie (draft persistence)
hooks/              use-user-guard, use-admin-guard, ...
zyra-engine/        the Virtual Office PixiJS engine — import from @/zyra-engine
i18n/ messages/     next-intl — locale in the zyra_locale cookie (URL never changes)

Auth / session

• The access token lives in memory only, via lib/auth/session.ts — never localStorage
• The refresh token is an httpOnly cookie; the zyra_token cookie is just a presence flag
• Two guard layers: proxy.ts (edge) and components/auth-guard.tsx (client) — a new public page must be added to PUBLIC_PATHS in both files

zyra-engine (the Virtual Office canvas)

Split into systems: InputSystem · CameraSystem · PlayerSystem · HitboxSystem · SitSystem · PlacementSystem. Core constants: TILE_SIZE=32, PLAYER_SPEED=120 px/s.

Movement is path-based: the engine fires onPathStarted → the client sends move_to (the path) → the server computes duration_ms and broadcasts moving → peers interpolate along the path → on arrival the client sends stop. Legacy move/moved is now only for non-positional state (sitting, direction).

Every new endpoint is Handler → Service → SQL inside the service. There is no ORM and no separate repository layer.

• Handler — take input, validate at the surface, return JSON
• Service — business logic, transactions, sentinel errors (ErrNotFound, ErrDuplicate)
• Model — cross-layer structs live in internal/model/

// response envelope — required on every endpoint
model.APIResponse{ Status: 200, Message: "success", Data: &logon, Token: token }

// transaction pattern
tx, err := s.db.BeginTx(ctx, pgx.TxOptions{})
if err != nil { return fmt.Errorf("begin tx: %w", err) }
defer tx.Rollback(ctx)
// ...
return tx.Commit(ctx)

Middleware / the permission line

Every upload goes to Cloudflare R2 through storage.S3Client, and only the public URL is stored in the DB. Never write permanent files to the API server's filesystem.

Connect to GET /ws?workspace_id=&token= — the JWT must be minted by zyra-api with the same tokenKey. Messages use a JSON envelope { "type": ..., "payload": ... }, except high-frequency moved updates, which are binary frames (type byte 0x01).

Things to know before editing zyra-ws

• AOI grid of 16×16 tiles — moved only reaches the 3×3 cell neighbourhood (~48×48 tiles), and only on the open floor; private rooms use room-level broadcast
• The server computes duration_ms = pathDistancePx / 120 * 1000 itself — clients don't get to decide
• All state lives in Redis with TTLs (vo:presence:* 35s, vo:last_pos:* 7 days, wave/knock cooldowns, …)
• Whenever a walk is cancelled, you must tell the other side — otherwise peers see warp-backs and avatars standing in walls

zyra-sfu knows no business rules at all (single presenter, force mute, capacity). Enforce those in zyra-ws/zyra-api.

These are enforced in review — breaking one means the PR doesn't land.

feat/<name>  ──▶  develop  ──▶  main  ──▶  tag v<x.y.z>
   local          dev        uat          prod
                auto deploy  auto deploy  auto deploy (gated)

git checkout develop && git pull origin develop
git checkout -b feat/<feature-name>    # or fix/<name>
# ...work, then push your own branch...
git push origin feat/<feature-name>

Release gate: go test ./... green · npm run lint + next build green · env vars complete on the target · migrations applied before deploy · /healthz returns 200 afterwards.