feat(backend): API versioning, pool metrics, tenant isolation, event-driven leaderboard cache

[joel-metal]

Summary

• Establish an API versioning strategy with a versioned route prefix #1111 – Versioned API route prefix (/api/v1). All routes mounted on a unified v1Router with /api kept as a backward-compat alias. Every response includes X-API-Version: v1 header.
• Expose database connection-pool health as Prometheus metrics #1112 – Prometheus connection-pool health metrics (db_connections_active, db_connections_idle, db_connections_waiting, db_pool_saturation). New poolMetrics.ts attaches a Prisma middleware to track in-flight query concurrency as a pool-utilisation proxy.
• Enforce tenant isolation for token data access #1113 – Tenant isolation for token data access. tenantMiddleware({ required: true }) applied to the tokens router; every Prisma query is scoped to creator = tenantId. Cache keys namespaced per tenant so slices never bleed across tenants. Requests without a resolvable tenant are rejected with HTTP 400.
• Refactor leaderboard caching with TTL-aware, event-driven invalidation #1114 – Event-driven leaderboard cache invalidation. leaderboardService subscribes to burn.created and token.created events via the shared eventBus and invalidates only the affected leaderboard type (scoped, not global). The 5-minute TTL remains as a safety net.

Changes

File	What changed
src/index.ts	Unified v1Router, /api/v1 canonical mount, /api compat alias, registerPoolMetrics call
src/lib/metrics/index.ts	Added db_connections_waiting + db_pool_saturation gauges; updated MetricsCollector.updateDatabaseConnections signature
src/lib/metrics/poolMetrics.ts	New – Prisma middleware that tracks in-flight queries → pool gauges
src/routes/tokens.ts	tenantMiddleware({ required: true }), tenant-scoped creator filter, tenant-namespaced cache keys
src/routes/tokens.test.ts	Updated to send X-Tenant-ID header; assertions include creator scope
src/services/leaderboardService.ts	Event subscriptions (burn.created, token.created), invalidateCacheByType(), TTL retained as fallback

Versioning policy

• /api/v1/ is the canonical versioned prefix going forward.
• /api/ is a permanent backward-compat alias pointing to the same router.
• The X-API-Version: v1 header is set on every response from v1Router.
• Future breaking changes introduce /api/v2 without removing v1.

Pool metric names

Metric	Type	Description
db_connections_active	Gauge	In-flight queries (≤ pool size)
db_connections_idle	Gauge	Idle pool slots
db_connections_waiting	Gauge	Queries queued beyond pool capacity
db_pool_saturation	Gauge	active / pool_size (alert on > 0.8)

Pool size configured via DB_POOL_SIZE env var (default: 10).

Leaderboard invalidation triggers

Event	Invalidated leaderboards
burn.created	most-burned, most-active, most-burners
token.created	newest, largest-supply

Publish these events from the burn/token write handlers:

await eventBus.publish("burn.created",  { tokenId });
await eventBus.publish("token.created", { tokenId });

Closes #1111
Closes #1112
Closes #1113
Closes #1114

🤖 Generated with Claude Code

[drips-wave]

@joel-metal Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits