Backend Architecture
API Surface
The backend exposes route groups for:
- auth and user profile management
- billing and credits
- sessions, pins, and wishlists
- REST chat APIs
- files and assets
- slides, storybooks, media, and templates
- projects, deployments, databases, and subdomains
- connectors, Composio, and prompt enhancement
- settings for models, MCP, and skills
The current codemap identifies 27 route groups across those domains.
Middleware Chain
The standard HTTP path includes:
- CORS
- session middleware
- request tracing
- exception logging
- GZip compression
Global exception handling sits above domain routers.
Realtime Command Layer
Socket.IO powers the high-interactivity surfaces. Key handler groups include:
- agent execution:
query,plan,continue_run,cancel - sandbox management: wake, status, workspace info
- project publishing and env saving
- Apple/mobile related handlers
- prompt enhancement and auth-adjacent flows
That handler layer is where agent sessions become streamed UI state.
Service and Repository Pattern
Representative mapping:
| Domain | Service | Repository layer |
|---|---|---|
| Sessions | SessionService | SessionRepository |
| Chat messages | MessageService | ChatMessageRepository |
| Projects | ProjectService | ProjectRepository |
| Slides | SlideService | SlideContentRepository |
| Connectors | ConnectorService | ConnectorRepository |
| Settings | LLMSettingService, MCPSettingService, SkillService | Per-domain repositories |
Auth and DI
Shared dependency aliases cover:
- current user resolution
- async DB sessions
- cached settings
- access to the application container
The codebase is opinionated about using aliases consistently so route signatures remain readable.
Billing and reliability concerns
The backend owns:
- Stripe-facing billing transactions
- credit balances and transactions
- usage metering and ledger updates
- enforcement that work only proceeds when the user can afford it
This makes billing a first-class backend concern rather than a UI-only surface.
Operational implications
Because the backend spans HTTP, realtime, billing, content generation, and deployment orchestration, documentation has to be explicit about:
- which env file controls which runtime
- which domain owns a bug or capability
- which commands validate health for each service