The state-server is one canonical state owner; avvy-worker is one async pipeline; avvy-app + avvy-engine are the web client. The supporting deployed services (contask, content-processor, texture-converter, webapp, avvy-landing, plus FoundationDB, Redis, monitoring) are documented in Deployed Services.
┌────────────────────────┐
│ avvy-app │ React 19 web client
│ (bundles avvy-engine)│ Three.js + WASM rendering
└────────────┬───────────┘
│ HTTPS + WebSocket (CBOR; JSON fallback)
▼
┌────────────────────────┐
│ state-server │ Go; clean-arch DDD
│ Entities · Sync · API │◄──┐
│ in-process JWT + OAuth │ │ signed CBOR callbacks
└─────┬────────────┬─────┘ │ (HMAC-SHA256)
│ │ │
▼ ▼ │
┌───────────┐ ┌───────────┐ │
│ MongoDB │ │ Redis │ │
│ or FDB │ │ + asynq │ │
│ (see ops) │ └─────┬─────┘ │
└───────────┘ │ │
▼ │
┌────────────┐ │
│ avvy-worker│────┘
│ 3D pipe │
└─────┬──────┘
│
▼
┌───────────┐
│ S3 │
│ (Hetzner) │
└───────────┘
state-server — Go backend (go.mod: Go 1.23.7). Owns Users, Branes (Group + IsBrane), Objects, Prototypes, Handlers. Clean-arch layout under internal/{domain, infrastructure, interfaces, services, common, jobs, monitoring, utils} (verified against the actual repo tree). Persistence is feature-flagged: code default is MongoDB (FDB_ENABLED=false in config/config.go), but the production Kubernetes pod waits for an fdb-cluster-file init container, so production runs against FoundationDB. Real-time sync via WebSocket (CBOR; JSON fallback per APP_DESCRIPTION.md). Auth is in-process (internal/interfaces/http/handlers/auth/) — JWT + OAuth (Google, Microsoft) + dev-mode fake auth.
avvy-worker — Go 1.25 async pipeline. Consumes asynq tasks from Redis (model.preview.v1, model.object_pipeline.v1, model.projection.step.v1, model.projection.model.v1). Eight verified provider integrations (OpenAI, KIE, Gemini, Replicate, Tencent, PIAPI, NanoBanana, FAL). Returns signed CBOR callbacks (HMAC-SHA256) to state-server. Stores artifacts in S3 (Hetzner Object Storage in production per ArgoCD).
avvy-app — React 19 web client. CBOR-encoded REST + WebSocket against state-server. Bundles avvy-engine as its renderer.
avvy-engine — Three.js r162 + AssemblyScript/WASM library. Built with Rollup into ESM + WASM bundles.
Deployed services — definitive list of services running in production, sourced from avvy/argocd Kustomization manifests. Includes the four above plus contask, content-processor, texture-converter, webapp, avvy-landing, FoundationDB cluster, Redis, monitoring stack, and infra (cert-manager, cloudflare external-dns, autoscaler, gitlab-runner).
Brane edit. Client → state-server (HTTPS/CBOR or WS/CBOR) → write to persistence layer → broadcast to subscribed peers via WebSocket.
3D model ingest. Client uploads → state-server enqueues asynq job in Redis → avvy-worker dequeues → runs preview/projection pipeline → POSTs HMAC-signed CBOR callback to state-server → state-server persists artifacts (S3 keys + metadata) and notifies the client over WS.
Auth. Client → state-server /auth/* (in-process) → JWT issued → token presented on every subsequent state-server request. OAuth callback paths exist for Google and Microsoft.
Wire format. CBOR preferred on REST and WebSocket; JSON is a supported fallback (per APP_DESCRIPTION.md).
IDs. UUID v4 strings (8-4-4-4-12).
Idempotency. Mutating /object, /prototype, /users requests require an Idempotency-Key header; keys scoped per user, 24-hour TTL.
Errors. Standardized error envelope (REST) and system.error frames (WebSocket).
Transform. [16]float32 4×4 column-major matrix on every spatial entity.
state-server/STATE_SERVER_COMPREHENSIVE_DESCRIPTION.md, state-server/docs/APP_DESCRIPTION.md, state-server/docs/openapi-v2.yml, state-server/docs/WEBSOCKET_PROTOCOL.md, state-server/internal/domain/entity/{types.go, objects.go}, state-server/config/config.go, state-server/internal/interfaces/http/router.go, avvy-worker/README.md, avvy-worker/cmd/avvy-worker/main.go, avvy/argocd deployment manifests.