# ADR-0007: Service Interaction Patterns and BFF Role

- 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.
