Eve library

Service Interaction Patterns

Guide

Revision 1

On this page

This guide captures how Lilith services communicate and how the BFF orchestrates requests.

Synchronous pattern (default)#

  • Clients talk only to the BFF.
  • BFF calls downstream services over REST (OpenAPI-covered).
  • Responses are adapted by the BFF for each channel (web/mobile/voice).
Sequence diagramSequence diagram: 5 participants and 8 messages.1Client to BFFPOST /v1/chat (token)2BFF to AuthGET /v1/auth/introspect3Auth to BFFuser + scopes4BFF to ConversationPOST /v1/conversations5Conversation to BFFconversationId6BFF to AIPOST /v1/ai/chat {conversationId, prompt}7AI to BFFChatResponse8BFF to ClientChannel-shaped reply (web/mobile/voice)
Sequence diagram: Sequence diagram. Sequence diagram: 5 participants and 8 messages.

Drawn from its Mermaid source.

As text
Participants:
- Client
- BFF
- Auth
- Conversation
- AI

Steps:
- 1. Client to BFF: POST /v1/chat (token)
- 2. BFF to Auth: GET /v1/auth/introspect
- 3. Auth to BFF: user + scopes (reply)
- 4. BFF to Conversation: POST /v1/conversations
- 5. Conversation to BFF: conversationId (reply)
- 6. BFF to AI: POST /v1/ai/chat {conversationId, prompt}
- 7. AI to BFF: ChatResponse (reply)
- 8. BFF to Client: Channel-shaped reply (web/mobile/voice) (reply)
Show source
sequenceDiagram
  participant Client
  participant BFF
  participant Auth
  participant Conversation
  participant AI

  Client->>BFF: POST /v1/chat (token)
  BFF->>Auth: GET /v1/auth/introspect
  Auth-->>BFF: user + scopes
  BFF->>Conversation: POST /v1/conversations
  Conversation-->>BFF: conversationId
  BFF->>AI: POST /v1/ai/chat {conversationId, prompt}
  AI-->>BFF: ChatResponse
  BFF-->>Client: Channel-shaped reply (web/mobile/voice)

Async side-effects (non-critical)#

  • Background jobs (notifications, analytics, cache invalidation) are emitted to queues/streams.
  • Core flows do not depend on eventual events; they complete synchronously.
sequenceDiagram participant BFF participant Notification participant Analytics BFF-->>Notification: emit "message.sent" event BFF-->>Analytics: emit "chat.turn" event Note over Notification,Analytics: Delivery is best-effort; core response already returned.

Testing and local validation#

  • Prefer app.inject() with Fastify to exercise routes without opening ports.
  • Avoid cross-service imports; use shared libraries (services/lib, services/common, token/meditation/transaction cores).

Anti-patterns to avoid#

  • Direct client → core service calls (bypass BFF).
  • Cross-service DB access or in-process imports.
  • Event-only implementations for core read/write flows where determinism is required.
  • ADR-0001 (microservices architecture)
  • ADR-0007 (service interaction patterns and BFF role)