state-server is the canonical state owner for the platform. It manages users, branes, objects, prototypes, and handlers; provides real-time multi-user sync; and exposes a CBOR-encoded REST + WebSocket API.
Repo: gitlab.avvyland.com/avvy/state-server. Production image: gitlab.avvyland.com:5050/avvy/state-server:latest (per avvy/argocd/state-server-all/base/deployment.yaml).
Language. Go 1.23.7 (go.mod).
Persistence. Feature-flagged. Code default is MongoDB (FDB_ENABLED defaults to false in config/config.go line 258); production sets FDB_ENABLED=true and waits for an FDB cluster file via an init container (verified in avvy/argocd/state-server-all/base/deployment.yaml). See Persistence Layer for the dual-mode details.
Cache. In-memory local cache + Redis distributed cache.
Queue producer. Redis + asynq (state-server enqueues, avvy-worker consumes).
WebSocket. gorilla/websocket with CBOR (fxamacker/cbor/v2) envelopes.
HTTP. HTTP/1.1, HTTP/2, HTTP/3 (QUIC via quic-go). TLS required in prod.
Auth. In-process. JWT (golang-jwt/jwt/v5), OAuth 2.0 (Google + Microsoft), dev-mode fake auth. Token blacklist in Redis. No separate auth_backend service in current code.
Scripting. Otto JS engine for handlers (server-side logic attached to prototypes).
internal/
├── common/
├── domain/
│ ├── entity/ Entity interfaces, ObjectBase, PrototypeBase, User, Handler,
│ │ Group, Block, SpacecellBase, spatial primitives.
│ ├── idempotency/ Idempotency-Key handling.
│ ├── modelpipeline/, modelpreview/, modelprojection/ Model-processing contracts.
│ ├── transaction/ Transaction management interfaces.
│ ├── walkthrough/ Brane walkthrough paths.
│ └── common/, TODO.md
├── infrastructure/ Persistence (MongoDB / FDB), cache (Redis + local),
│ auth providers, secret manager, email, WebSocket hub.
├── interfaces/
│ └── http/
│ ├── handlers/{admin, analytics, auth, brane, company, entity, health,
│ │ modelpipeline, modelpreview, modelprojection, privacy,
│ │ user, walkthrough, websocket}
│ └── router.go
├── jobs/ Background jobs (popularity index, TTL cleanup).
├── monitoring/ Observability glue.
├── services/ Application services (use cases).
└── utils/
Tree verified against state-server/internal/ directly.
Source: state-server/internal/domain/entity/types.go and objects.go.
User (types.go:369) — authentication identity, profile, inventory, ownership.
Object (umbrella term; ObjectBase interface at types.go:233) — implementations are Group and Block.
Group (objects.go) — container with child objects, gallery of prototypes; carries IsBrane bool (line 199–200). A "Brane" is a Group with IsBrane: true — there is no separate Brane Go type.
Block — leaf 3D object with model, transform, properties.
Prototype (PrototypeBase interface at types.go:256) — versioned template with is_public, is_deprecated, is_deleted flags. Supports prototype-group prototypes too (PrototypeGroupBase, ObjectGroupBase).
Handler (types.go:344) — server-side Otto JS attached to a prototype.
SpacecellBase (types.go:444) — spatial cell.
Spatial primitives:
SpatialKey [4]int32 (line 470) — coordinate index.Space map[SpatialKey]SpacecellBase (line 761) — Go type alias for spatial indexing. Not a top-level container.Transform [16]float32 (line 503) — 4×4 column-major matrix.Not present in code: Karma, Curator, NPC, separate Brane type, "Portal"/"Teleport" types. Anything claiming these in earlier wiki text was incorrect.
Verified by reading internal/interfaces/http/handlers/:
admin/ analytics/ auth/ brane/ company/ entity/ health/ modelpipeline/ modelpreview/ modelprojection/ privacy/ user/ walkthrough/ websocket/.
The credit-related surface is currently restricted to GET /users/{id}/credits/transactions (audit-trail listing; viewer can only see own credits) — see internal/interfaces/http/handlers/user/handler.go:394. There are no wallet, billing, commerce, entitlement, or supplier-earnings handler packages in the current code. The Financial Backend design described in state-server-master-task-spec-2026-04-20/docs/FINANCIAL_BACKEND.md is a future addition; this page will be updated when the corresponding handlers land.
Encoding. CBOR preferred; JSON fallback supported (per APP_DESCRIPTION.md).
IDs. UUID v4 strings (8-4-4-4-12).
Idempotency. Required on mutating /object, /prototype, /users — Idempotency-Key header, per-user scope, 24-hour TTL (docs/openapi-v2.yml).
go build -o scene-server # local binary
go test ./... # full suite
go test -race ./... # race detector
go test -cover ./... # coverage
go fmt ./... && go vet ./... # hygiene
Run with a populated .env (persistence URI(s), JWT secret, TLS cert/key, worker callback URLs + secrets). Production loads its environment from state-server-secrets and state-server-config Kubernetes objects (per the ArgoCD deployment manifest).
Outbound to avvy-worker. Enqueues asynq jobs in Redis (model.preview.v1, model.object_pipeline.v1, model.projection.step.v1, model.projection.model.v1). Verifies HMAC-signed CBOR callbacks on internal callback endpoints.
Outbound to S3. Stores model bytes, processed CBOR, canonical GLBs, preview images.
Inbound from clients. Serves REST + WebSocket traffic from avvy-app, webapp, JS SDK consumers.
state-server/internal/domain/entity/types.go, state-server/internal/domain/entity/objects.go, state-server/internal/interfaces/http/router.go, state-server/internal/interfaces/http/handlers/*, state-server/config/config.go, state-server/STATE_SERVER_COMPREHENSIVE_DESCRIPTION.md, state-server/docs/openapi-v2.yml, state-server/docs/WEBSOCKET_PROTOCOL.md, avvy/argocd/state-server-all/base/deployment.yaml.