FHIR Group Member Search Flow

System Design · sequence diagram · MIT

Illustrates the data flow for searching FHIR Groups by a specific member using a FHIR API, a storage provider, ClickHouse for member indexing, and MongoDB

Source: https://github.com/icanbwell/fhir-server/blob/97ba98f5a1285179af54cbd4a17fb9334a728d0c/readme/clickhouse.md
Curated by icanbwell
FHIR Group Member Search API MongoDB ClickHouse

Mermaid source

sequenceDiagram
    participant Client
    participant API as FHIR API
    participant Provider as MongoWithClickHouse<br/>StorageProvider
    participant CH as ClickHouse
    participant Mongo as MongoDB

    Client->>API: GET /4_0_0/Group?member=Patient/123
    API->>Provider: findAsync(query)

    Note over Provider: Detect member search parameter
    Provider->>Provider: Extract member criteria<br/>from MongoDB query

    Provider->>CH: SELECT group_id<br/>FROM Group_4_0_0_MemberCurrentByEntity<br/>WHERE entity_reference = 'Patient/123'<br/>AND event_type = 'added'

    Note over CH: Uses argMax aggregation<br/>for current state
    CH-->>Provider: [groupId1, groupId2, ...]

    Provider->>Mongo: find({_id: {$in: [groupId1, groupId2]}})
    Mongo-->>Provider: [Group metadata...]

    Note over Provider: Groups returned WITHOUT<br/>member arrays (stripped)

    Provider-->>API: Groups[]
    API-->>Client: 200 OK Bundle

What this diagram shows

This sequence diagram details how a client initiates a search for FHIR Groups based on a member reference (e.g., Patient/123). The FHIR API delegates to a storage provider which detects the member search. It then queries ClickHouse for group IDs associated with the member, leveraging argMax for current state. Finally, it fetches group metadata from MongoDB, stripping member arrays before returning a bundle to the client.

When to use it

Use this pattern when designing or documenting a system that requires efficient, scalable lookup of parent entities (like FHIR Groups) by their associated child entities (members), especially when the member list can be very large or frequently updated, and a fast analytical store like ClickHouse is available for indexing.

How to adapt it for your project

This architecture can be adapted for any system needing to quickly find parent records based on child attributes. Replace FHIR with your domain, and adapt the storage providers (e.g., PostgreSQL for ClickHouse, Cassandra for MongoDB) while maintaining the core idea of using a specialized index for the 'member' lookup and a primary store for the main entity metadata.

Key concepts