Last updated 2026-05-03

Service-to-service communication

AI-generated content

This document was generated by an AI assistant. Verify accuracy before relying on the details.

Patterns

ADB combines three communication patterns:

Synchronous HTTP between Java microservices, via the reactive WebClient and the FQDN enum.
Asynchronous events over AWS SQS / SNS.
Edge BFF on Cloudflare Workers (adb-web) for browser-side requests.

1. Synchronous HTTP — the `FQDN` enum

Every Java service declares its targets through a centralized enum at adb/adb-common/src/main/java/fr/lifeconnect/adb/client/FQDN.java.

FQDN	Internal URL	Target service	In monorepo
`PERSONS`	`http://adb-persons`	adb-persons	✓
`ORGANIZATIONS`	`http://adb-persons` (same service)	adb-persons	✓
`PARTS`	`http://adb-parts`	adb-parts	✓
`CONTRACTS`	`http://adb-contracts`	adb-contracts	✓
`ACCOUNTING`	`http://adb-accounting`	adb-accounting	✓
`FILES`	`http://adb-files`	adb-files	✓
`UTILITIES`	`http://adb-utilities`	adb-utilities	✓
`AGGREGATES`	`http://adb-aggregates`	adb-aggregates	✓
`VIEWS`	`http://adb-views`	adb-views	✓
`REPORTS`	`http://adb-reports`	adb-reports	✓
`TICKETS`	`http://adb-tickets`	adb-tickets	✓
`GRAPH`	`http://adb-graph`	adb-graph	✗ (deprecated)
`NOTES`	`http://adb-notes`	adb-notes	✗ (deprecated)
`NOTIFICATIONS`	`http://adb-notifications`	adb-notifications	✗ (deprecated)
`UI` / `UI_EXT`	`http://adb-ui` / `http://adb-ui-ext`	adb-ui	✓

DNS resolution is handled by Kubernetes: each Helm chart (adb-charts/charts/services/) creates a Service named after the microservice, which makes http://adb-persons directly resolvable from any other pod.

Outbound call matrix

flowchart LR
    persons[adb-persons]
    parts[adb-parts]
    contracts[adb-contracts]
    accounting[adb-accounting]
    files[adb-files]
    utilities[adb-utilities]
    aggregates[adb-aggregates]
    views[adb-views]
    reports[adb-reports]
    tickets[adb-tickets]

    persons --> files

    parts --> persons
    parts --> contracts
    parts --> utilities

    contracts --> persons
    contracts --> parts
    contracts --> files
    contracts --> accounting
    contracts --> utilities

    accounting --> persons
    accounting --> parts
    accounting --> contracts
    accounting --> files
    accounting --> utilities

    aggregates --> persons
    aggregates --> parts
    aggregates --> contracts
    aggregates --> files
    aggregates --> utilities

    views --> persons
    views --> parts
    views --> contracts
    views --> files

    reports --> aggregates
    
    tickets --> persons
    tickets --> parts
    tickets --> contracts
    tickets --> files
    tickets --> utilities

adb-utilities and adb-files call no other service (they are leaves).

2. Gateway — `adb/proxy` (Nginx)

The proxy module of the parent project exposes an Nginx API gateway that routes external requests to the services. Paths follow the /<service>/... pattern:

/persons/* → adb-persons
/parts/* → adb-parts
/contracts/* → adb-contracts
/accounting/* → adb-accounting
/files/* → adb-files
/utilities/* → adb-utilities
/aggregates/* → adb-aggregates
/view/* → adb-views (note: /view, singular)
/reports/* → adb-reports
/tickets/* → adb-tickets
/notes/* → ⚠ redirects to adb-tickets (notes is deprecated)

Keycloak authentication is validated by each service (OAuth2 resource server), not by the gateway.

3. Cloudflare BFF — `adb-web/apps/bff`

For new frontend flows, adb-web inserts a BFF (Backend-For-Frontend) running on Cloudflare Workers, written in Hono. Its responsibilities:

Terminate authentication at the edge (Keycloak JWT validation).
Cache idempotent reads (KV namespace, planned).
Rate-limit per user (Durable Objects, planned).
Fan out to the Java services through a Cloudflare Tunnel (secret ADB_TUNNEL_TOKEN, upstream ADB_UPSTREAM_URL).

sequenceDiagram
    participant U as Browser
    participant UI as adb-web/ui (Worker)
    participant BFF as adb-web/bff (Worker)
    participant T as Cloudflare Tunnel
    participant GW as adb/proxy (Nginx)
    participant S as Java microservice

    U->>UI: GET /index.html
    UI-->>U: SPA + assets
    U->>BFF: GET /api/contracts (Bearer JWT)
    BFF->>BFF: Verify JWT, read KV cache
    alt Cache miss
        BFF->>T: HTTPS over tunnel
        T->>GW: Internal HTTP
        GW->>S: GET /contracts
        S-->>GW: 200 JSON
        GW-->>T: 200 JSON
        T-->>BFF: 200 JSON
        BFF->>BFF: Store in cache
    end
    BFF-->>U: 200 JSON

As of today, only the /healthz endpoint is implemented in apps/bff/src/index.ts; business routes still need to be wired up.

4. Asynchronous events — AWS SQS / SNS

Services emit change events (create / update / delete) onto SNS topics, which are consumed by interested services through SQS queues (with DLQs).

Main producers / consumers

Event	Producer	Consumers
`onPersonModified`	adb-persons	adb-contracts, adb-accounting, adb-views
`onOrganizationModified`	adb-persons	adb-accounting
`onPartModified`	adb-parts	adb-contracts, adb-views
`onChargeModified`	adb-parts	adb-views
`onMarketPerformanceModified`	adb-parts	adb-views
`onContractModified` / `onContractUpdated`	adb-contracts	adb-accounting, adb-views
`onDirectDebitProcessed`	adb-contracts	adb-accounting
`onIndexPublished`	adb-utilities	adb-contracts
`onPaymentModified`	adb-accounting	adb-accounting
`onAccountingEventModified` / `onAccountingEntryModified`	adb-accounting	adb-accounting, adb-views
`onFileUploaded`	adb-files	adb-files
`onFileMetaDataModified`	adb-files	adb-contracts, adb-views
`onTicketModified` / `onTicketEventModified`	adb-tickets	adb-views
`dunningNoticeSent`	adb-contracts	adb-contracts

The shared adb-messaging module (under adb/) wraps SnsTemplate and SqsListener via Spring Cloud AWS 3.0.4. Region: eu-west-1.

Event flow diagram

flowchart LR
    persons[adb-persons] -.->|onPerson*| sns((SNS))
    parts[adb-parts] -.->|onPart*<br/>onCharge*| sns
    contracts[adb-contracts] -.->|onContract*<br/>onDirectDebitProcessed| sns
    accounting[adb-accounting] -.->|onAccounting*<br/>onPayment*| sns
    files[adb-files] -.->|onFileUploaded<br/>onFileMetaDataModified| sns
    utilities[adb-utilities] -.->|onIndexPublished| sns
    tickets[adb-tickets] -.->|onTicket*| sns

    sns --> q1[SQS adb-contracts]
    sns --> q2[SQS adb-accounting]
    sns --> q3[SQS adb-views]

    q1 --> contracts2[adb-contracts]
    q2 --> accounting2[adb-accounting]
    q3 --> views[adb-views]

adb-views is the largest consumer: it maintains denormalized projections for the dashboards and listens to 8 SQS queues simultaneously.

Per-service dependency summary

See each service's individual page for the exact list of FQDNs called and queues consumed.