Use Case
Internal product APIs with embedded ClickHouse analytics
This is the migration path for teams that already have a backend and do not want to split it into a separate analytics service on day one. Keep the existing routes, move the query logic onto a shared path, and expose more only when it earns its place.
Contract impact
Zero endpoint breakage
Execution model
In-process + routed
Migration style
Endpoint-by-endpoint
Keep route contracts stable
Existing consumers do not need to notice the migration while you move analytics logic behind an internal path.
Use one query definition
Let handlers call `api.run(...)` directly and expose the same definition over HTTP only where it is genuinely useful.
Scale rollout safely
Start with one endpoint or one response shape, see what sticks, then widen the internal surface deliberately.
Implementation flow
Step 1
Mount internal routes
Mount the analytics handler beside the routes you already run instead of restructuring the whole backend first.
Step 2
Compose in endpoints
Pull analytics into existing business responses without turning every route into bespoke query code.
Step 3
Reuse query logic
Keep one typed source of truth whether the query is called directly or exposed under an internal path.
Works with your existing routes
The route tree stays yours. Add the analytics surface where it fits instead of adopting a separate service boundary immediately.
Compose analytics directly in business endpoints
Use `api.run(...)` when a product response needs analytics context but does not need another network hop inside the same backend.
Define once, reuse everywhere
The same definition can back an internal route and an in-process call, which is the whole point of this adoption path.
Ready to implement
Use this as your first production migration path
- Keep existing consumer contracts intact
- Move the query logic into one typed definition
- Expose more surface area only when the team actually needs it