- 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#
-
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. -
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.
-
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.
-
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. -
No cross-service database access. Each service owns its persistence layer; other services consume data via service APIs only.
-
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(); addinject-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.mdfor request/sequence examples.docs/module-system.mdfor import/module guidance.- Existing ADRs 0001 (microservices architecture) and 0004–0006 (shared cores) for related boundaries.