# stanfordspezi/spezifhir architecture

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

- Interactive diagram: https://gitdiagram.com/stanfordspezi/spezifhir
- Repository: https://github.com/stanfordspezi/spezifhir

## Overview

##### Project Type and Purpose
- SpeziFHIR is a Swift Package (see Package.swift) providing reusable modules for FHIR data handling, HealthKit integration, and mock patient data.
- It’s intended to be embedded into a mobile app built on the Spezi framework to manage FHIR resources locally, convert HealthKit samples to FHIR, handle attachments, and support testing.

##### Core Components
A. SpeziFHIR (Core FHIR Library)
– FHIRResource submodule
- Category, Copy, Search, Stringify, LockManager, ResourceProxy
– FHIRAttachment submodule
- Base64Decoding, ContentExtractor, PDFDocumentProviding, FHIRAttachmentService
– FHIRStore
- Local store for reading/writing FHIR resources
– Extensions
- Convenience date extensions for various FHIR resource types
B. SpeziFHIRHealthKit
– Maps HealthKit samples → FHIRResource models
– Extends FHIRStore to load attachments and persist HealthKit‐derived data
C. SpeziFHIRMockPatients
– Supplies FHIRBundle “mock patients” resources + selectors
– Testing‐support extensions on FHIRStore for injecting mock data
D. Tests
– Unit tests for each submodule under Tests/SpeziFHIRTests
– UI tests (Tests/UITests/TestApp) demonstrating package in a dummy app

##### External Services / Frameworks
- HealthKit (iOS API) – data source for FHIRHealthKit module
- PDFKit / Base64 – for attachment decoding & extraction
- Spezi application (host app) – uses package modules via SwiftPM

##### Relationships & Data Flows
- Host App → imports SpeziFHIR & configures FHIRStore
- SpeziFHIRHealthKit reads HealthKit samples → transforms into FHIRResource → persists via FHIRStore
- Host App reads from FHIRStore → drives UI
- Host App / SpeziFHIRAttachmentService handles attachments (e.g., fetch embedded base64, decode, extract PDF/text)
- In tests, SpeziFHIRMockPatients injects mock FHIRBundle into FHIRStore → UI Tests reuse same FHIRStore interface

##### Architectural Patterns & Principles
- Modular layering: Core FHIR logic is independent of HealthKit & Mock data modules
- Dependency injection: Host app provides FHIRStore instance to submodules
- Single responsibility: each submodule focuses on one domain (resources, attachments, HealthKit, mocking)
- Extensibility: extension files under Sources/SpeziFHIR/Extensions demonstrate open‐extension points

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host App
    HostApp["Host App (Spezi-based iOS App)"]:::host

    %% External Services
    HK["HealthKit"]:::external
    PDF["PDFKit/Base64"]:::external

    %% SpeziFHIR Package Boundary
    subgraph "SpeziFHIR Swift Package"
        direction TB
        subgraph "Core"
            direction TB
            FHIRResource["FHIRResource Submodule"]:::module
            FHIRAttachment["FHIRAttachment Submodule"]:::module
            FHIRStore["FHIRStore"]:::module
            Extensions["Extensions"]:::module
        end
        subgraph "SpeziFHIRHealthKit"
            HealthKitModule["HealthKit Module"]:::module
        end
        subgraph "SpeziFHIRMockPatients"
            MockPatients["MockPatients Module"]:::module
        end
    end

    %% Tests and Config
    UnitTests["Unit Tests"]:::test
    UITests["UI Tests"]:::test
    TestApp["TestApp (Dummy Host App)"]:::host
    PackageManifest["Package.swift"]:::config
    CI["CI/CD Workflows"]:::config

    %% Data Flows
    HostApp -->|imports & configures| FHIRStore
    HostApp -->|reads/writes| FHIRStore
    HostApp -->|handles attachments via| FHIRAttachment

    HK -->|sample data| HealthKitModule
    HealthKitModule -->|transform & persist| FHIRStore

    FHIRAttachment -->|decode attachment| PDF

    UnitTests -->|tests modules| FHIRResource
    UnitTests -->|tests modules| FHIRAttachment
    UnitTests -->|tests modules| FHIRStore
    UnitTests -->|tests modules| HealthKitModule
    UnitTests -->|injects mock data| MockPatients

    MockPatients -->|inject mock bundles| FHIRStore

    UITests -->|runs in| TestApp
    TestApp -->|uses mock data| MockPatients
    TestApp -->|configures| FHIRStore

    %% Click Events
    click FHIRResource "https://github.com/stanfordspezi/spezifhir/tree/main/Sources/SpeziFHIR/FHIRResource"
    click FHIRAttachment "https://github.com/stanfordspezi/spezifhir/tree/main/Sources/SpeziFHIR/FHIRAttachment"
    click FHIRStore "https://github.com/stanfordspezi/spezifhir/blob/main/Sources/SpeziFHIR/FHIRStore.swift"
    click Extensions "https://github.com/stanfordspezi/spezifhir/tree/main/Sources/SpeziFHIR/Extensions"
    click HealthKitModule "https://github.com/stanfordspezi/spezifhir/tree/main/Sources/SpeziFHIRHealthKit"
    click MockPatients "https://github.com/stanfordspezi/spezifhir/tree/main/Sources/SpeziFHIRMockPatients"
    click TestApp "https://github.com/stanfordspezi/spezifhir/tree/main/Tests/UITests/TestApp"
    click PackageManifest "https://github.com/stanfordspezi/spezifhir/blob/main/Package.swift"
    click CI "https://github.com/stanfordspezi/spezifhir/blob/main/.github/workflows/build-and-test.yml"

    %% Styles
    classDef module fill:#add8e6,stroke:#333,stroke-width:1px
    classDef external fill:#90ee90,stroke:#333,stroke-width:1px
    classDef host fill:#ffd700,stroke:#333,stroke-width:1px
    classDef test fill:#ffebcd,stroke:#333,stroke-width:1px
    classDef config fill:#e0e0e0,stroke:#333,stroke-width:1px
```
