Eve library

ADR-0007: Service Interaction Patterns and BFF Role

ADR

Revision 1

On this page
  • Status: Accepted
  • Date: 2025-02-07
  • Authors: Claude Code Assistant

Context#

Lilith runs dozens of Fastify-based microservices (auth, content, conversation, ai, media, notification, etc.) behind a backend-for-frontend (BFF). Recent work standardized service scaffolding and module systems, but how services interact was not captured in an ADR. We need clear guidance on:

  • Which protocols to prefer (REST vs internal events).
  • How the BFF should orchestrate service calls.
  • How to avoid tight coupling and cross-service reach-through.

Decision#

  1. Client-facing traffic goes through the BFF. All user/API requests terminate at services/bff, which orchestrates downstream calls and shapes responses per channel. No direct client calls to core services.

  2. Synchronous intra-service calls use REST over HTTP with explicit contracts. Services expose REST endpoints with OpenAPI coverage. The BFF and peer services call these endpoints; no in-process imports across service boundaries.

  3. Async fan-out uses events only for non-critical paths. Background workflows (notifications, analytics, cache invalidation) use queue/event streams; core read/write flows remain synchronous for determinism.

  4. Fastify app.inject() for tests and local validation. Ad-hoc scripts and tests should prefer in-process injection instead of starting servers to keep feedback fast and avoid port conflicts.

  5. No cross-service database access. Each service owns its persistence layer; other services consume data via service APIs only.

  6. Response envelopes are shaped in the BFF. Downstream services return domain-native payloads; the BFF adapts to client/channel needs (web/mobile/voice) to prevent presentation logic leaking into core services.

Rationale#

  • Keeps a single ingress (BFF) for auth, rate limiting, and response shaping.
  • REST with OpenAPI maintains clear contracts and is easiest to test and observe.
  • Event-driven paths are limited to non-critical side effects, reducing eventual-consistency risk in core flows.
  • app.inject() pattern aligns with repo guidance and avoids long-lived servers in CI/local runs.
  • Data ownership boundaries prevent schema coupling and accidental tight coupling.
  • BFF response shaping avoids duplication across clients and keeps services focused on domain concerns.

Consequences#

  • Services must expose and maintain REST endpoints; OpenAPI validation remains part of CI.
  • Background jobs should flow through queues/streams and be optional for core success paths.
  • Tests should avoid app.listen(); add inject-based coverage instead.
  • Any new client surface must go through the BFF; direct exposure of core services is discouraged.
  • Cross-service imports of code or DB access are disallowed; use shared libraries (services/lib, services/common, token-core, etc.) for reusable logic.

Alternatives Considered#

  • Direct client-to-service calls: Rejected to avoid inconsistent auth, rate limits, and response shapes.
  • Heavy event-first architecture for all flows: Rejected for core read/write paths to keep determinism and reduce latency/complexity.
  • GraphQL gateway: Not chosen for now; REST + BFF meets current needs with lower operational overhead.

References#

  • docs/service-interaction-patterns.md for request/sequence examples.
  • docs/module-system.md for import/module guidance.
  • Existing ADRs 0001 (microservices architecture) and 0004–0006 (shared cores) for related boundaries.