Avvyland is a microservice constellation with one canonical state owner (state-server), one async pipeline (avvy-worker), one web client (avvy-app + avvy-engine), and supporting subsystems for assets, storage, auth, and infrastructure.
┌────────────────────────┐
│ avvy-app │ React 19 web client
│ (uses avvy-engine) │ Three.js + WASM rendering
└────────────┬───────────┘
│ HTTPS + WebSocket (CBOR)
▼
auth_backend ┌────────────────────────┐
(JWT) │ state-server │ Go; clean-arch DDD
─────────────►│ Entities · Sync · API│◄──┐
│ JWT auth · Handlers │ │ signed CBOR callbacks
└─────┬────────────┬─────┘ │ (HMAC-SHA256)
│ │ │
▼ ▼ │
┌───────────┐ ┌───────────┐ │
│ MongoDB │ │ Redis │ │
│ replica │ │ + asynq │ │
│ set │ └─────┬─────┘ │
└───────────┘ │ │
▼ │
┌────────────┐ │
│ avvy-worker│────┘
│ 3D pipe │
└─────┬──────┘
│
▼
┌───────────┐
│ S3 + │
│ storage │
└───────────┘
state-server — Go 1.23+ backend. Owns Users, Branes, Objects, Prototypes, Handlers, Karma balances. Implements clean architecture with internal/domain, internal/infrastructure, internal/interfaces, internal/services layers. Two-tier storage: MongoDB for persistence (replica-set required for ACID), Redis for cache and queue. Real-time sync via WebSocket. Encodes all wire payloads as CBOR.
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). Processes 3D models via Playwright/Three.js, OpenAI Vision, Hunyuan 3D, Replicate. Returns signed CBOR callbacks (HMAC-SHA256) to state-server. Stores artifacts in S3.
avvy-app — React 19 + Vite/Craco web client. CBOR-encoded REST + WebSocket against state-server. Integrates Shopify App Bridge. Bundles avvy-engine as its renderer.
avvy-engine — JS/TS rendering library on Three.js r162 + AssemblyScript-compiled WASM. Exports Engine, material classes (PBR, Hologram, Portal, Wind), UI manager, entity-schema system. Built with Rollup into ESM + WASM bundles.
Asset pipeline — Go library avvy-view-handlers (GLB import, image compression); graphic-engine, postprocessing, texture-compressor, texture-convertor, assets-builder, metabox, three.js fork. (The earlier UCS family is obsolete and removed from scope.)
Storage — avvy/storage (the prior avvy-storage, storage-workers, and blocks-admin siblings are obsolete and removed from scope).
Auth + Identity — auth_backend issues JWTs against L1-attached user identities; sha3.net provides SHA3 crypto utilities.
Infrastructure — argocd, rancher-autoscaler, monitoring, uptime-checker, load-testing (Locust at locust.k8s.avvyland.com), turnProxy, route-server, grid-server.
Brane edit. Client → state-server (HTTPS/CBOR or WS/CBOR) → MongoDB write → 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 → auth_backend (JWT issuance) → token presented on every state-server request.
Karma transactions. Client action → state-server handler script (Otto) evaluates economic rules → ACID multi-document transaction on MongoDB → confirmation over WS.
Wire format. CBOR over HTTPS and WebSocket. No JSON on the hot path.
IDs. UUID v4 strings (8-4-4-4-12).
Errors. Standardized ErrorMessageResponse envelope.
Cache invalidation. Automatic on writes through the cache layer.
Contexts with timeouts. Required on every MongoDB and worker operation.