Architecture
Request Flow
All API endpoints use Restate's HTTP invocation pattern: POST /<package.ServiceName>/<Method> with a JSON (protojson) request body.
Gateway Routing
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.
| Gateway | Domain | Downstream |
|---|---|---|
| LLM Gateway | Conversations | ConversationManagerActor, MCPService, MemoryService |
| Socayo Gateway | Health Coaching | SocayoUserActor |
| Storage Gateway | Storage | StorageManagerActor |
| Integrations Gateway | Integrations | PipedreamService |
| Webhook Gateway | Webhooks | WebhookService |
| Notification Gateway | Notifications | Novu REST API |
| Auth Gateway | Auth | ApiKeyService |
Actors
Stateful components keyed by ID. Each actor instance maintains its own state via Restate's durable state.
| Actor | Key | Purpose |
|---|---|---|
| ConversationActor | conversation_key | Individual conversation state and message history |
| ConversationManagerActor | user_id | Per-user conversation management (list, create, delete) |
| SocayoUserActor | user_id | User profile and onboarding data |
| StorageManagerActor | user_id | Per-user file storage operations and quota |
| FirebaseBridgeActor | user_id | Firebase 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
- Pipecat / Daily / Cerebrium — Voice AI pipeline
Workflows
Long-running orchestrations that coordinate multiple services.
| Workflow | Purpose |
|---|---|
| SocayoPlanGeneratorWorkflow | Generate coaching plans from user profiles |
| GenerationWorkflow | Content generation with LLM |
| DeploymentWorkflow | Service deployment orchestration |
Infrastructure
Deployment
Services are built with ko (Go) or Docker, pushed to GHCR, and automatically deployed via Flux image automation policies.