feat(persistence): MongoDB backend with CRUD, search, history, and transactions

.github/workflows/inferno.yml

@@ -1,7 +1,7 @@
 name: Inferno US Core Test Suite
 
 on:
-  workflow_dispatch:  # Manual trigger only for initial implementation
+  workflow_dispatch: # Manual trigger only for initial implementation
 
 env:
   CARGO_TERM_COLOR: always
@@ -35,7 +35,7 @@ jobs:
           echo 'rustflags = ["-C", "link-arg=-fuse-ld=lld", "-C", "link-arg=-Wl,-zstack-size=8388608"]' >> ~/.cargo/config.toml
 
       - name: Build HFS
-        run: cargo build -p helios-hfs --features R4,sqlite,elasticsearch,postgres
+        run: cargo build -p helios-hfs --features R4,sqlite,elasticsearch,postgres,mongodb
 
       - name: Upload HFS binary
         uses: actions/upload-artifact@v4
@@ -52,8 +52,16 @@ jobs:
       fail-fast: false
       max-parallel: 3
       matrix:
-        suite_id: [us_core_v311, us_core_v400, us_core_v501, us_core_v610, us_core_v700, us_core_v800]
-        backend: [sqlite, sqlite-elasticsearch, postgres]
+        suite_id:
+          [
+            us_core_v311,
+            us_core_v400,
+            us_core_v501,
+            us_core_v610,
+            us_core_v700,
+            us_core_v800,
+          ]
+        backend: [sqlite, sqlite-elasticsearch, postgres, mongodb]
         include:
           - { suite_id: us_core_v311, version_label: "v3.1.1" }
           - { suite_id: us_core_v400, version_label: "v4.0.0" }
@@ -129,6 +137,50 @@ jobs:
 
           echo "OMITTED_TESTS=[${OMITTED}]" >> $GITHUB_ENV
 
+      - name: Start MongoDB replica set
+        if: matrix.backend == 'mongodb'
+        run: |
+          MONGO_CONTAINER="mongo-${{ matrix.suite_id }}-${{ matrix.backend }}-${{ github.run_id }}-${{ github.run_attempt }}"
+          docker rm -f "$MONGO_CONTAINER" 2>/dev/null || true
+          docker run -d --name "$MONGO_CONTAINER" -p 0:27017 mongo:8.0 --replSet rs0 --bind_ip_all
+
+          echo "MONGO_CONTAINER=$MONGO_CONTAINER" >> $GITHUB_ENV
+
+          READY=0
+          for i in {1..30}; do
+            if docker exec "$MONGO_CONTAINER" mongosh --quiet --eval 'db.adminCommand({ ping: 1 }).ok' > /dev/null 2>&1; then
+              READY=1
+              break
+            fi
+            echo "Attempt $i/30: MongoDB not ready yet..."
+            sleep 2
+          done
+
+          if [ "$READY" -ne 1 ]; then
+            echo "MongoDB failed to start"
+            docker logs "$MONGO_CONTAINER"
+            exit 1
+          fi
+
+          docker exec "$MONGO_CONTAINER" mongosh --quiet --eval 'try { rs.status(); } catch (e) { rs.initiate({ _id: "rs0", members: [{ _id: 0, host: "localhost:27017" }] }); }' > /dev/null 2>&1
+
+          echo "Waiting for MongoDB replica set primary..."
+          for i in {1..60}; do
+            PRIMARY_STATE=$(docker exec "$MONGO_CONTAINER" mongosh --quiet --eval 'try { rs.status().myState } catch (e) { 0 }' | tr -d '\r\n ')
+            if [ "$PRIMARY_STATE" = "1" ]; then
+              MONGO_PORT=$(docker port "$MONGO_CONTAINER" 27017 | head -1 | sed 's/.*://')
+              echo "MongoDB replica set is ready on port $MONGO_PORT"
+              echo "MONGO_PORT=$MONGO_PORT" >> $GITHUB_ENV
+              exit 0
+            fi
+            echo "Attempt $i/60: MongoDB replica set not primary yet..."
+            sleep 2
+          done
+
+          echo "MongoDB replica set failed to become primary"
+          docker logs "$MONGO_CONTAINER"
+          exit 1
+
       - name: Start Elasticsearch
         if: matrix.backend == 'sqlite-elasticsearch'
         run: |
@@ -204,6 +256,12 @@ jobs:
             HFS_PG_USER=helios \
             HFS_PG_PASSWORD=helios \
             ./target/debug/hfs --log-level info --port $HFS_PORT --host 0.0.0.0 > "$HFS_LOG" 2>&1 &
+          elif [ "${{ matrix.backend }}" = "mongodb" ]; then
+            MONGO_HOST="${DOCKER_HOST_IP:-127.0.0.1}"
+            HFS_STORAGE_BACKEND=mongodb \
+            HFS_DATABASE_URL="mongodb://$MONGO_HOST:$MONGO_PORT/?replicaSet=rs0&directConnection=true" \
+            HFS_MONGODB_DATABASE="helios_inferno_${{ matrix.suite_id }}_${{ github.run_id }}_${{ github.run_attempt }}" \
+            ./target/debug/hfs --log-level info --port $HFS_PORT --host 0.0.0.0 > "$HFS_LOG" 2>&1 &
           else
             ./target/debug/hfs --database-url :memory: --log-level info --port $HFS_PORT --host 0.0.0.0 > "$HFS_LOG" 2>&1 &
           fi
@@ -472,4 +530,7 @@ jobs:
           echo "Stopping PostgreSQL..."
           docker rm -f "${PG_CONTAINER:-none}" 2>/dev/null || true
 
+          echo "Stopping MongoDB..."
+          docker rm -f "${MONGO_CONTAINER:-none}" 2>/dev/null || true
+
           echo "Cleanup complete"

.gitignore

@@ -17,3 +17,6 @@ AGENTS.md
 *.db
 *.db-shm
 *.db-wal
+
+# Test artifacts
+/test-artifacts

ROADMAP.md

@@ -1,6 +1,5 @@
 # Helios FHIR Server — Roadmap
 
->
 > This document outlines the development direction for the Helios FHIR Server. It is organized into three horizons — **Now**, **Next**, and **Later** — to set expectations without overpromising timelines. Items may shift between horizons as priorities evolve based on community feedback, production needs, and contributor availability.
 >
 > Want to influence the roadmap? Join our [weekly developer meeting](#community) or comment on a [GitHub Discussion](https://github.com/HeliosSoftware/hfs/discussions).
@@ -16,12 +15,16 @@ These capabilities are available today in the current release.
 - [FHIR REST API server](crates/hfs/README.md) with CRUD operations, search, history, and batch/transaction support
 
 **Persistence**
+
 - [SQLite as a primary store](crates/persistence/README.md#sqlite-default)
 - [SQLite as a primary store with Elasticsearch as a query secondary](crates/persistence/README.md#sqlite--elasticsearch)
 - [PostgreSQL as a primary store](crates/persistence/README.md#postgresql)
 - [PostgreSQL as a primary store with Elasticsearch as a query secondary](crates/persistence/README.md#postgresql--elasticsearch)
+- [MongoDB as a primary store](crates/persistence/README.md#mongodb)
+- [MongoDB as a primary store with Elasticsearch as a query secondary](crates/persistence/README.md#mongodb--elasticsearch)
 
 **Analytics & Tooling**
+
 - [SQL on FHIR](crates/sof/README.md) — CLI and HTTP server
 - [FHIRPath expression engine](crates/fhirpath/README.md) — CLI and HTTP server
 - [Python bindings (pysof)](crates/pysof/README.md)
@@ -32,14 +35,13 @@ These capabilities are available today in the current release.
 
 Work that is currently underway or planned for the near term.
 
-| Area | Item | Status |
-|------|------|--------|
-| **Compliance** | Audit logging (AuditEvent resource support) | 🔵 Design |
-| **Standards** | FHIR Validation engine | 🔵 Design |
-| **Standards** | Authentication & Authorization | 🔵 Design |
-| **Documentation** | Project documentation website | 🔵 Design |
-| **Persistence** | MongoDB as a primary store | 🟡 In progress |
-| **Persistence** | S3 as a primary store | 🟡 In progress |
+| Area              | Item                                        | Status         |
+| ----------------- | ------------------------------------------- | -------------- |
+| **Compliance**    | Audit logging (AuditEvent resource support) | 🔵 Design      |
+| **Standards**     | FHIR Validation engine                      | 🔵 Design      |
+| **Standards**     | Authentication & Authorization              | 🔵 Design      |
+| **Documentation** | Project documentation website               | 🔵 Design      |
+| **Persistence**   | S3 as a primary store                       | 🟡 In progress |
 
 ### Discussion Documents
 
@@ -57,19 +59,22 @@ We are actively developing community discussion documents on the following topic
 These items are well-understood and will be picked up once current work completes.
 
 ### FHIR Server Capabilities
+
 - **Bulk Data API** — Import and export (`$export` / `$import` operations)
 - **FHIR Subscriptions** — Topic-based notification support
 - **Terminology Server** — CodeSystem `$lookup`, ValueSet `$expand`, ConceptMap `$translate`
 - **SMART on FHIR** — Full launch framework and scoped access
-- **SQL on FHIR** — [SQL on FHIR operations](https://sql-on-fhir.org/ig/latest/operations.html) - using read-only database connections 
+- **SQL on FHIR** — [SQL on FHIR operations](https://sql-on-fhir.org/ig/latest/operations.html) - using read-only database connections
 
 ### Persistence Backends
+
 - Cassandra as a primary store
 - ClickHouse as a primary store
 - S3 with Elasticsearch as a query secondary
 - Cassandra with Elasticsearch as a query secondary
 
 ### Developer Experience
+
 - **Administrative UI** — Web-based management console for server configuration and monitoring
 - **MCP Server for FHIR API** — Model Context Protocol integration for the FHIR REST API
 - **MCP Server for SQL on FHIR** — Model Context Protocol integration for analytics workflows
@@ -82,11 +87,14 @@ These items are well-understood and will be picked up once current work complete
 Longer-term ideas we are exploring. These are not yet committed and may evolve significantly based on community input.
 
 ### Advanced Persistence
+
 - Neo4j as a primary store
 - PostgreSQL with Neo4j as a graph query secondary
 
 ### Persistence Advisor
+
 An intelligent recommendation engine for storage configuration:
+
 - Analyze a FHIR query and recommend an optimal persistence configuration
 - Leverage historical benchmark data to inform recommendations
 - Web UI for interactive configuration guidance
@@ -95,10 +103,10 @@ An intelligent recommendation engine for storage configuration:
 
 ## Status Legend
 
-| Icon | Meaning |
-|------|---------|
-| 🟡 | In progress — actively being developed |
-| 🔵 | Design — in planning or community discussion phase |
+| Icon | Meaning                                            |
+| ---- | -------------------------------------------------- |
+| 🟡   | In progress — actively being developed             |
+| 🔵   | Design — in planning or community discussion phase |
 
 ---
 
@@ -119,4 +127,4 @@ We welcome contributors and feedback at every level — from opening issues to j
 
 ---
 
-*This roadmap is a living document. It does not represent a commitment or guarantee to deliver any feature by any particular date. Items may be reprioritized based on community needs, production feedback, and resource availability.*
+_This roadmap is a living document. It does not represent a commitment or guarantee to deliver any feature by any particular date. Items may be reprioritized based on community needs, production feedback, and resource availability._