Aidbox: A Technical Deep Dive into a Comprehensive FHIR Server Solution

(def code-system-schema
  {:resourceType {:type "string" :constant "CodeSystem"}
  :url {:type "string" :required true}
  :version {:type "string"}
  :name {:type "string"}
  :title {:type "string"}
  :status {:type "string" :enum ["draft" "active" "retired" "unknown"]}
  :experimental {:type "boolean"}
  :date {:type "dateTime"}
  :publisher {:type "string"}
  :description {:type "string"}
  :caseSensitive {:type "boolean"}
  :valueSet {:type "string"}
  :hierarchyMeaning {:type "string" :enum ["grouped-by" "is-a" "part-of" "classified-with"]}
  :compositional {:type "boolean"}
  :versionNeeded {:type "boolean"}
  :content {:type "string" :enum ["not-present" "example" "fragment" "complete" "supplement"]}
  :supplements {:type "string"}
  :count {:type "integer"}
  :concept {:type "array"
            :schema {:type "object"
                      :schema {:code {:type "string" :required true}
                              :display {:type "string"}
                              :definition {:type "string"}
                              :designation {:type "array"}
                              :property {:type "array"}
                              :concept {:type "array" :refers "concept"}}}}})

The terminology service implements these key operations:

▪️$lookup: Retrieve concept details from a CodeSystem
▪️$validate-code: Validate if a code is valid in a given context
▪️$subsumes: Check hierarchical relationships between concepts
▪️$compose: Create value sets from code system expressions
▪️$expand: Expand a ValueSet into its full list of codes

Each operation is implemented with performance optimizations like:

▪️In-memory caching of frequently used code systems
▪️Materialized views for common expansions
▪️Prefix trie structures for concept lookup by code

Technical Deep Dive: Security Implementation

Aidbox implements a comprehensive security model that extends beyond basic OAuth 2.0:

Access Control Engine

The access control system uses a Policy Decision Point (PDP) architecture with attribute-based access control:

(defn evaluate-access [request context policies]
  (let [applicable-policies (filter #(policy-applies? % request context) policies)
        decisions (map #(evaluate-policy % request context) applicable-policies)]
    (if (some #(= :deny %) decisions)
      {:decision :deny}
      (if (some #(= :allow %) decisions)
        {:decision :allow}
        {:decision :deny :reason :no-applicable-policy}))))

GET /.well-known/smart-configuration

/auth/authorize?response_type=code&client_id=my-app&redirect_uri=https://app.example.com/callback&scope=patient/*.read&state=random-state-string&aud=https://aidbox.example.com/fhir

POST /auth/token
grant_type=authorization_code&code=issued-code&redirect_uri=https://app.example.com/callback&client_id=my-app

GET /fhir/Patient/123
Authorization: Bearer eyJhbGci...

{ns aidbox
import #{aidbox.patient}

SpecialPatient
{:zen/tags #{zen/schema zen/entity}
  :type zen/map
  :extends #{aidbox.patient/Patient}
  :keys
  {:specialNeeds {:type zen/boolean}
  :priorityScore {:type zen/integer
                  :min 0
                  :max 100}
  :careCoordinator {:type zen/map
                    :keys {:reference {:type zen/string}
                          :display {:type zen/string}}}}}
}

{:zen/tags #{aidbox/service}
:engine aidbox.zen/http-rpc
:method post
:uri "/calculate-risk-score"
:format :json
:middleware [{:type auth/authorization
              :policy :require-admin}]
:handler
(fn [ctx]
  (let [patient-id (get-in ctx [:params :patient-id])
        patient (db/get-resource "Patient" patient-id)
        score (calculate-risk-score patient)]
    {:status 200
      :body {:score score}}))}

# Excerpt from k8s deployment manifests
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: aidbox-db
spec:
  serviceName: aidbox-db
  replicas: 3
  selector:
    matchLabels:
      app: aidbox-db
  template:
    metadata:
      labels:
        app: aidbox-db
    spec:
      containers:
      - name: postgres
        image: postgres:13
        volumeMounts:
        - name: data
          mountPath: /var/lib/postgresql/data
        env:
        - name: POSTGRES_USER
          valueFrom:
            secretKeyRef:
              name: aidbox-secrets
              key: db-user
        # Additional environment variables...
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: [ "ReadWriteOnce" ]
      resources:
        requests:
          storage: 100Gi

The Kubernetes deployment includes:

▪️StatefulSets for database persistence
▪️Deployments for stateless application nodes
▪️ConfigMaps for environment-specific configuration
▪️Secrets for sensitive information
▪️Services for internal and external access
▪️Ingress for routing and TLS termination
▪️HorizontalPodAutoscalers for dynamic scaling

Technical Integration Patterns

FHIR ETL Pipeline Implementation

Aidbox provides tools for building ETL pipelines for legacy data migration:

# Sample ETL mapping definition
(def patient-mapping
  {:resourceType "Patient"
  :id {:path [:PatientID] :transform str}
  :meta {:profile ["http://example.org/fhir/StructureDefinition/ExamplePatient"]}
  :active true
  :name [{:family {:path [:LastName]}
          :given [{:path [:FirstName]}
                  {:path [:MiddleName]}]
          :prefix [{:path [:Title]}]}]
  :gender {:path [:Gender]
            :transform #(case %
                          "M" "male"
                          "F" "female"
                          "O" "other"
                          "unknown")}
  :birthDate {:path [:DOB]
              :transform #(when % (format-date % "MM/dd/yyyy" "yyyy-MM-dd"))}})

# Pipeline execution
(defn transform-patients [data-source]
  (let [raw-patients (fetch-legacy-data data-source)
        fhir-patients (map #(transform-resource patient-mapping %) raw-patients)]
    (doseq [batch (partition-all 100 fhir-patients)]
      (save-batch "Patient" batch))))

# Kafka producer configuration
(def kafka-config
  {:bootstrap.servers "kafka:9092"
  :key.serializer "org.apache.kafka.common.serialization.StringSerializer"
  :value.serializer "org.apache.kafka.common.serialization.StringSerializer"})

# FHIR subscription handler
(defn handle-subscription-event [resource-type id event]
  (let [resource (db/get-resource resource-type id)
        message {:resource-type resource-type
                :id id
                :event event
                :timestamp (now)
                :resource resource}
        topic (str "fhir." resource-type "." event)]
    (with-open [producer (KafkaProducer. kafka-config)]
      (.send producer (ProducerRecord. topic id (json/encode message))))))

# $expand operation implementation excerpt
(defmethod operation "ValueSet/$expand"
  [{{:keys [url count filter]} :params :as request}]
  (let [value-set (resolve-value-set url)
        expansion (expand-value-set value-set {:count count :filter filter})]
    {:status 200
    :body {:resourceType "ValueSet"
            :url url
            :expansion {:timestamp (now)
                        :contains expansion}}}))

# Optimized expansion algorithm
(defn expand-value-set [{:keys [compose] :as vs} {:keys [count filter]}]
  (let [included (mapcat expand-component (:include compose))
        excluded (set (mapcat expand-component (:exclude compose)))
        filtered (if filter
                  (filter #(string/includes?
                              (string/lower-case (or (:display %) ""))
                              (string/lower-case filter))
                          included)
                  included)
        result (remove #(contains? excluded (:code %)) filtered)
        limited (if count (take count result) result)]
    limited))

# Validation engine invocation
(defn validate-resource [resource profile-urls]
  (let [resource-type (:resourceType resource)
        base-profile (str "http://hl7.org/fhir/StructureDefinition/" resource-type)
        all-profiles (conj (or profile-urls []) base-profile)
        structure-definitions (map resolve-structure-definition all-profiles)
        validation-context {:resource resource
                          :structure-definitions structure-definitions}]
    (validate validation-context)))

# FHIRPath evaluation
(defn evaluate-fhirpath [resource expression]
  (let [parsed-expr (parse-fhirpath expression)
        context {:context resource
                :resource resource}]
    (evaluate-expr parsed-expr context)))