# santeonnl/orca architecture

> Architecture diagram of the GitHub repository santeonnl/orca, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santeonnl/orca
- Repository: https://github.com/santeonnl/orca

## Overview

##### Project type and purpose
- ORCA is a full-stack, microservices-style platform implementing the Shared Care Planning FHIR specification.
- It consists of:
- A Go-based backend (“orchestrator”) that exposes internal and external FHIR APIs, implements Care Plan Contributor and optional Care Plan Service roles, handles OIDC/OAuth2, messaging, discovery, subscriptions, and acts as a proxy to EHR FHIR APIs.
- One primary Next.js frontend for care professionals.
- Two auxiliary Next.js simulators (hospital_simulator and viewer_simulator) as demo/test clients.
- Helm charts and Docker definitions for Kubernetes/Azure deployments.

##### File structure
- Top-level directories:
- “frontend”: Next.js application for real care professionals.
- “hospital_simulator” & “viewer_simulator”: Next.js demo apps with DashboardLayout, API routes for FHIR, delivery, bgz, and authentication flows.
- “orchestrator”: Go microservice with subpackages:
– careplancontributor (Task placement/filling, Task engine, OIDC clients)
– careplanservice (CarePlan/CareTeam management, FHIR operations, webhook)
– messaging (Azure ServiceBus, in-memory, HTTP)
– healthcheck, events, user/session, ADR, cmd entrypoints
– lib/* (coolfhir client, az key vault, crypto, otel, validation, etc.)
– util (CLI utilities)
- “deployments”: Helm charts (orca, nuts, nuts-admin, fhir) and local Docker-Compose for dev.
- “e2e-tests”: Go-based integration tests driving orchestrator and simulators.

##### Key points from README
- ORCA’s high-level roles:
- Frontend UI for Task negotiation and CarePlan viewing.
- Orchestrator as Care Plan Contributor and optional Care Plan Service, proxying FHIR APIs.
- Integration with local EHR FHIR API, external SCP nodes, Nuts discovery, and OAuth2/OIDC servers.
- External dependencies: Azure Key Vault, Azure Service Bus, SQL for Nuts, any FHIR R4 API.

##### Final advice
- Be exhaustive: break the orchestrator into its major subdomains.
- Real deployment boundaries (containers, clusters, services).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Local Care Provider Cluster
    subgraph "Local Care Provider"
        direction TB
        EHR["EHR System\n(FHIR API)"]:::external
        subgraph "Orchestrator Service" 
            direction TB
            OFHIR_INT["Internal-Facing\nFHIR API"]:::orchestrator
            OFHIR_EXT["External-Facing\nFHIR API"]:::orchestrator
            CPC["CarePlanContributor\n(module)"]:::orchestrator
            CPS["CarePlanService\n(module)"]:::orchestrator
            TASK["Task Engine"]:::orchestrator
            OIDC["OIDC/OAuth2\nAuthorization"]:::orchestrator
            DISC["Discovery\n(Nuts Node)"]:::orchestrator
            MSG["Messaging\n(Azure Service Bus)"]:::infra
            DB["Database\n(SQL for Nuts)"]:::infra
            KV["Key Vault\n(Azure Key Vault)"]:::infra
        end
        FE["Frontend UI\n(Next.js)"]:::ui
    end

    %% External Care Providers Cluster
    subgraph "External Care Providers"
        direction TB
        ExtCPS["CarePlanService\n(Remote FHIR API)"]:::external
        ExtCPC["CarePlanContributor\n(Remote FHIR API)"]:::external
        ExtOIDC["Auth Server\n(OAuth2/OIDC)"]:::external
    end

    %% Demo Simulators Cluster
    subgraph "Demo Simulators"
        direction TB
        HS["Hospital Simulator\n(Next.js)"]:::ui
        VS["Viewer Simulator\n(Next.js)"]:::ui
    end

    %% Infrastructure Cluster
    subgraph "Infrastructure & CI/CD"
        direction TB
        K8s["Kubernetes\n/Azure Container Apps"]:::infra
        Helm["Helm Charts\n(deployments/)"]:::infra
        CICD["CI/CD Pipelines\n(.github/workflows)"]:::infra
    end

    %% Relationships
    FE -->|"HTTP /api/FHIR"| OFHIR_INT
    FE -->|"/launch"| OFHIR_INT
    OFHIR_INT -->|FHIR R4| EHR
    FE -->|"Create CarePlan/Task"| CPS
    CPS -->|"SQL R/W"| DB
    CPS -->|"webhook/subscription"| MSG
    MSG -->|"notify"| OFHIR_INT
    TASK -->|"invoke"| OFHIR_EXT
    TASK -->|"OIDC token"| OIDC
    TASK -->|"FHIR R4"| ExtCPS
    TASK -->|"FHIR R4"| ExtCPC
    DISC -->|SQL R/W| DB
    DISC -->|"resolve DID"| ExtCPS
    HS -->|"FHIR /delivery API"| OFHIR_INT
    HS -->|"auth flows"| OFHIR_INT
    VS -->|"FHIR /delivery API"| OFHIR_INT
    CICD -->|"build/deploy"| Helm
    Helm -->|"deploy"| K8s

    %% Click Events
    click FE "https://github.com/santeonnl/orca/tree/main/frontend/"
    click HS "https://github.com/santeonnl/orca/tree/main/hospital_simulator/"
    click VS "https://github.com/santeonnl/orca/tree/main/viewer_simulator/"
    click OFHIR_INT "https://github.com/santeonnl/orca/blob/main/orchestrator/main.go"
    click OFHIR_INT "https://github.com/santeonnl/orca/blob/main/orchestrator/cmd/server.go"
    click OFHIR_EXT "https://github.com/santeonnl/orca/blob/main/orchestrator/cmd/config.go"
    click KV "https://github.com/santeonnl/orca/tree/main/orchestrator/util/"
    click DB "https://github.com/santeonnl/orca/blob/main/orchestrator/healthcheck/service.go"
    click MSG "https://github.com/santeonnl/orca/blob/main/orchestrator/events/manager.go"
    click CPC "https://github.com/santeonnl/orca/blob/main/orchestrator/user/session.go"
    click CPS "https://github.com/santeonnl/orca/blob/main/orchestrator/ADR.md"
    click CPC "https://github.com/santeonnl/orca/tree/main/orchestrator/careplancontributor/"
    click CPS "https://github.com/santeonnl/orca/tree/main/orchestrator/careplanservice/"
    click MSG "https://github.com/santeonnl/orca/tree/main/orchestrator/messaging/"
    click DISC "https://github.com/santeonnl/orca/tree/main/orchestrator/cmd/profile/nuts/"
    click DISC "https://github.com/santeonnl/orca/tree/main/orchestrator/cmd/tenants/"
    click KV "https://github.com/santeonnl/orca/tree/main/orchestrator/lib/"
    click Helm "https://github.com/santeonnl/orca/tree/main/deployments/charts/"
    click Helm "https://github.com/santeonnl/orca/tree/main/deployments/dev/"
    click CICD "https://github.com/santeonnl/orca/tree/main/e2e-tests/"

    %% Styles
    classDef ui fill:#DDEEFF,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#EEFFDD,stroke:#333,stroke-width:1px
    classDef external fill:#FFDDCC,stroke:#333,stroke-width:1px
    classDef infra fill:#DDDDDD,stroke:#333,stroke-width:1px
```
