Skip to main content

Architecture

Request Flow​

Request flow — client requests pass through KrakenD to Restate domain gateways, which fan out to actors, services, and workflows; actors and services publish events to Kafka while workflows chain service calls

Clients access the platform through KrakenD, which maps friendly REST paths to internal Restate services: POST /api/v1/<domain>/<service>/<method> with a JSON (protojson) request body.

Gateway Routing​

Gateway routing — public and internal gateways route to actors, services, and external integrations; edge colors indicate the calling gateway type

Component Types​

Gateways​

Stateless Restate services that extract auth context from request headers (x-user-id, x-user-email) and route to downstream actors, services, or workflows via the Restate SDK.

GatewayDomainDownstream
LLM GatewayConversationsConversationManagerActor, MCPService, MemoryService
Socayo GatewayHealth CoachingSocayoUserActor
Storage GatewayStorageStorageManagerActor
Integrations GatewayIntegrationsPipedreamService
Webhook GatewayWebhooksWebhookService
Notification GatewayNotificationsNotificationService → Novu REST API
Auth GatewayAuthApiKeyService

Actors​

Stateful components keyed by ID. Each actor instance maintains its own state via Restate's durable state.

Actor state model — each actor instance is keyed (e.g. by user_id) and maintains durable state accessed via SharedContext for reads and ObjectContext for writes

ActorKeyPurpose
ConversationActorconversation_keyIndividual conversation state and message history
ConversationManagerActoruser_idPer-user conversation management (list, create, delete)
SocayoUserActoruser_idUser profile and onboarding data
StorageManagerActoruser_idPer-user file storage operations and quota
FirebaseBridgeActoruser_idFirebase Auth token bridge

Services​

Stateless processors that handle specific integrations or computations.

  • OpenRouter — LLM inference via OpenRouter API
  • MCP — Model Context Protocol tool server management
  • Pinecone — Vector database operations
  • Memory — Mem0 memory search and management
  • Storage — Object storage backend (S3-compatible)
  • OpenFGA — Fine-grained authorization checks
  • Pipedream — Third-party app integrations
  • NotificationService — Multi-channel notification delivery via Novu
  • Pipecat / Daily / Cerebrium — Voice AI pipeline (in progress — not yet generally available)

Workflows​

Long-running orchestrations that coordinate multiple services.

Workflow — a trigger starts a workflow that calls services in sequence, each step durable and retried on failure until the final result is produced

WorkflowPurpose
GenerationWorkflowContent generation with LLM
DeploymentWorkflowService deployment orchestration

Error Handling​

All services use a standardized RpcError structure for error responses and event payloads. Errors are classified as terminal (non-retryable, returned to the client) or retryable (Restate will retry automatically).

{
  "code": "ERROR_CODE_MODEL_INVALID",
  "message": "model google/gemini-2.5-flash not found in catalog",
  "is_terminal": true,
  "details": {
    "error_info": {
      "reason": "MODEL_NOT_FOUND",
      "domain": "openrouter",
      "metadata": {
        "model_id": "google/gemini-2.5-flash"
      }
    },
    "model_error": {
      "model_id": "google/gemini-2.5-flash",
      "reason": "invalid"
    },
    "upstream_error": {
      "provider": "openrouter",
      "status_code": 400
    }
  }
}

The ErrorCode enum defines 25 standardized codes (e.g., ERROR_CODE_INVALID_ARGUMENT, ERROR_CODE_UNAUTHENTICATED, ERROR_CODE_RESOURCE_EXHAUSTED, ERROR_CODE_MODEL_INVALID) that map to HTTP status codes at the gateway boundary. Structured ErrorDetails can include upstream context, model context, retry hints, field violations, and help links.

Infrastructure​

Infrastructure layout — compute, messaging, storage, security, integrations, and LGTM observability stacks with the flow of telemetry from OTel collector into Loki, Tempo, Mimir, and queries from Grafana

Deployment​

Deployment — CI builds images on tag push and pushes them to GHCR; Flux image reflector scans GHCR, image automation updates tags via git commits, and source and kustomize controllers apply the manifests to the cluster

Services are built with ko (Go) or Docker, pushed to GHCR, and automatically deployed via Flux image automation policies.