Designing For Future Separation

Summary

Future database, service, and deployment splits are easier when current code already respects conceptual boundaries.

Problem

Today, one repo and one database can make direct access feel harmless. A route can query analytics state, a pipeline can publish operational side effects, or a job can call a provider directly. Each shortcut becomes expensive when the platform later needs separate databases, services, permissions, or deployment cadence.

Principle

Write code as if likely future separations are real. Keep access behind services, make publish steps explicit, normalize provider data inward, and preserve thin runtime adapters.

Platform Shape

The architecture docs treat app routes as adapters, services as capability surfaces, integrations as provider edges, and pipelines as deterministic data movement. That design gives future splits obvious boundaries: app surfaces can move separately from services, OLTP state can split from analytics, and provider adapters can be isolated behind integration packages.

The current monorepo still gives fast local coordination. Future separation is not a reason to prematurely distribute everything; it is a reason to keep contracts clean now.

Source Evidence

  • docs/reference/architecture.md
  • AGENTS.md
  • services
  • pipelines
  • docs/engineering/architecture/lakehouse-service-boundary.md
  • docs/engineering/architecture/explicit-publish-steps.md