​
Databases

Each SynapseX service owns its own tables. In local development, services default to SQLite. In production, set DATABASE_URL to PostgreSQL and keep service ownership boundaries intact.

​
Service-Owned Tables

ServiceTablesPurpose
api-gatewayagents, mcp_toolsPublic API agent records and seeded MCP catalog
tenant-servicetenants, tenant_membersOrganizations, plans, limits, members
event-bus-serviceeventsDurable event queue with ack/nack/dead-letter states
workspace-serviceworkspaces, artifactsAgent workspaces, outputs, generated files and reports
webhook-servicewebhook_subscriptions, webhook_deliveriesSubscriptions, signed delivery attempts and retries
update-servicereleases, rolloutsVM agent/runtime versions and rollout targeting
model-registry-servicemodelsModel catalog metadata, provider, capabilities, pricing metadata
observability-servicetelemetry_eventsTraceable service events and summaries
mcp-router-servicemcp_servers, mcp_plansMCP registry, routing decisions and explainable plans
Existing services such as billing, auth, audit, policy, secrets, VM registry and agent registry continue to own their own tables.

​
Runtime Configuration

Every new service supports: 
DATABASE_URL=postgresql://user:password@host:5432/synapsex
Local defaults use SQLite files, for example: 
sqlite:///./mcp_router.db
The backend-only compose file stores SQLite databases in named Docker volumes under /data.

​
Production Rules

  • Prefer one PostgreSQL database with service-owned schemas or separate databases per service.
  • Do not let Chat write directly to internal service tables.
  • Chat, CLI and SDK must go through api-gateway.
  • Service-to-service migrations should be explicit before production rollout.
  • Do not share ORM models across services unless they are part of packages/contracts.

​
MCP Router Persistence

mcp-router-service stores:
  • mcp_servers: registered MCP surfaces such as qcos-mcp and synapsex-ops-mcp.
  • mcp_plans: generated plans shown to users before approval/execution.
This lets Chat and CLI explain why a tool was selected and allows later audit/analytics.

​
Event And Audit Relationship

Use event-bus-service for operational events that drive workflows. Use audit-service for compliance records that should answer “who did what, when, and was it successful?” Use observability-service for operational telemetry and trace-level debugging.