← Part 2: Multi-Tenant Architecture

The Legacy Database Problem

Here's a real example from one of our tenants:

Hospital A stores patients like this:

CREATE TABLE pacientes (
    id_paciente INT PRIMARY KEY,
    rut_pac VARCHAR(12),
    nom_pac VARCHAR(100),
    ap_pat_pac VARCHAR(50),
    ap_mat_pac VARCHAR(50),
    fec_nac_pac DATE,
    sexo_pac CHAR(1)  -- 'M' or 'F'
);

Hospital B stores patients like this:

CREATE TABLE usuarios (
    id_usr INT PRIMARY KEY,
    rut_usr VARCHAR(15),
    nombre_usr VARCHAR(150),
    fecha_nacimiento DATE,
    usr_activo TINYINT  -- 0 or 1
);

Both need to map to the same FHIR Patient resource:

{
  "resourceType": "Patient",
  "id": "12345",
  "identifier": [{"value": "12345678-9"}],
  "name": [{"family": "Garcia", "given": ["Juan"]}],
  "birthDate": "1985-03-15",
  "gender": "male",
  "active": true
}

The challenge: How do we map arbitrary database schemas to FHIR without writing custom code for each tenant?

Solution: Dynamic Mapping Configuration

Instead of code generation or hardcoded mappings, I built a configuration-driven mapping engine that translates between databases and FHIR at runtime.

The Mapping Model

Each tenant defines table mappings and field mappings:

pub struct TableMapping {
    pub fhir_resource_type: String,      // "Patient"
    pub database_table_name: String,     // "pacientes" or "usuarios"
    pub database_schema: Option<String>, // Some tenants use schemas
}

pub struct FieldMapping {
    pub fhir_path: String,          // "name[0].family"
    pub database_column: String,    // "ap_pat_pac"
    pub data_type: DataType,        // String, Integer, Boolean, Date
    pub transformation_id: Option<i32>,  // Optional data transformation
    pub is_required: bool,
    pub is_primary_key: bool,
}

Tenants configure these via an admin panel (more on that in Part 5).

FHIR Path Parser: Navigating Nested Structures

FHIR is deeply nested. A patient's family name isn't just name—it's name[0].family.

I built a FHIR path parser that handles:

• Simple fields: id, gender, birthDate

• Array access: name[0], identifier[1]

• Nested fields: name[0].family, identifier[0].value

• Array filters: identifier[use='official'].value (future)

pub enum PathSegment {
    Field(String),           // "name"
    ArrayIndex(usize),       // [0]
    ArrayFilter {            // [use='official']
        key: String,
        value: String,
    },
}

pub struct FhirPath {
    segments: Vec<PathSegment>,
}

impl FhirPath {
    // Parse "name[0].family" into segments
    pub fn parse(path: &str) -> Result<Self> {
        let mut segments = Vec::new();
        let mut current = String::new();

        for ch in path.chars() {
            match ch {
                '.' => {
                    if !current.is_empty() {
                        segments.push(PathSegment::Field(current.clone()));
                        current.clear();
                    }
                }
                '[' => {
                    if !current.is_empty() {
                        segments.push(PathSegment::Field(current.clone()));
                        current.clear();
                    }
                    // Parse array index or filter...
                }
                _ => current.push(ch),
            }
        }

        if !current.is_empty() {
            segments.push(PathSegment::Field(current));
        }

        Ok(FhirPath { segments })
    }

    // Set a value in FHIR JSON using this path
    pub fn set(&self, resource: &mut JsonValue, value: JsonValue) -> Result<()> {
        let mut current = resource;

        for (i, segment) in self.segments.iter().enumerate() {
            let is_last = i == self.segments.len() - 1;

            match segment {
                PathSegment::Field(name) => {
                    if is_last {
                        current[name] = value.clone();
                        return Ok(());
                    } else {
                        // Navigate deeper, creating structure if needed
                        if !current.get(name).is_some() {
                            // Check what the next segment needs
                            if matches!(self.segments.get(i + 1), Some(PathSegment::ArrayIndex(_))) {
                                current[name] = json!([]);  // Create array
                            } else {
                                current[name] = json!({});  // Create object
                            }
                        }
                        current = &mut current[name];
                    }
                }
                PathSegment::ArrayIndex(idx) => {
                    if let JsonValue::Array(arr) = current {
                        // Ensure array is large enough
                        while arr.len() <= *idx {
                            arr.push(json!({}));
                        }

                        if is_last {
                            arr[*idx] = value.clone();
                            return Ok(());
                        } else {
                            current = &mut arr[*idx];
                        }
                    }
                }
                _ => {}
            }
        }

        Ok(())
    }
}

Type Inference: When the Database Lies

Here's a nasty surprise: MySQL stores booleans as TINYINT (0 or 1). But FHIR expects true or false.

Similarly, many legacy systems store IDs as INT, but FHIR requires them as strings.

I built a type inference system that knows the FHIR spec:

fn infer_fhir_type_from_path(fhir_path: &str) -> Option<DataType> {
    let path_lower = fhir_path.to_lowercase();

    // Boolean fields
    if path_lower == "active"
        || path_lower.ends_with(".active")
        || path_lower == "deceased" {
        return Some(DataType::Boolean);
    }

    // String fields (even if DB stores as INT)
    if fhir_path == "id"
        || path_lower.ends_with(".id")
        || path_lower.contains("identifier") {
        return Some(DataType::String);
    }

    // Date fields
    if path_lower == "birthdate"
        || path_lower.ends_with(".date") {
        return Some(DataType::Date);
    }

    None  // Use DB type
}

During mapping, the engine:

1. Reads value from database (e.g., TINYINT 1)

2. Checks if FHIR expects a specific type

3. Converts: 1 → true, 42 → "42", etc.

Transformations: Beyond Simple Type Conversion

Sometimes you need more than type conversion. Examples:

• Enum mapping: 'M' → "male", 'F' → "female"

• String combination: Join first_name + last_name into name[0].given

• Date formatting: DD/MM/YYYY → YYYY-MM-DD

I built a transformation system:

pub enum TransformationType {
    EnumMapping,    // Map values (M → male)
    Combine,        // Join array elements
    Split,          // Split string into array
    Format,         // Date/time formatting
    Conditional,    // If-then-else logic
}

pub struct Transformation {
    pub name: String,
    pub transformation_type: TransformationType,
    pub configuration: JsonValue,  // Type-specific config
}

Example transformation for gender:

{
  "name": "Gender M/F to FHIR",
  "transformation_type": "enum_mapping",
  "configuration": {
    "M": "male",
    "F": "female",
    "I": "other"
  }
}

The transformation engine applies these before setting the FHIR value:

pub fn transform_to_fhir(
    &self,
    value: &DbValue,
    transformation_id: Option<i32>,
    target_type: Option<DataType>,
) -> Result<JsonValue> {
    // 1. Convert DB value to JSON with type awareness
    let mut json_value = dbvalue_to_json_with_type(value, target_type);

    // 2. Apply transformation if specified
    if let Some(id) = transformation_id {
        if let Some(transformation) = self.transformations.get(&id) {
            json_value = self.apply_transformation(&json_value, transformation)?;
        }
    }

    Ok(json_value)
}

The Mapping Process: Putting It All Together

When a request comes in for GET /fhir/Patient/123:

pub async fn to_fhir(
    &self,
    resource_type: &str,
    db_row: &HashMap<String, DbValue>,
) -> Result<JsonValue> {
    // 1. Get field mappings for this resource type
    let table_mapping = self.config.get_table_mapping(resource_type)?;
    let field_mappings = &table_mapping.field_mappings;

    // 2. Start with base FHIR resource
    let mut fhir_resource = json!({
        "resourceType": resource_type
    });

    // 3. Map each field
    for field_mapping in field_mappings {
        // Get database value
        let db_value = match db_row.get(&field_mapping.database_column) {
            Some(val) if !matches!(val, DbValue::Null) => val,
            _ => continue,  // Skip missing/null values
        };

        // Infer expected FHIR type
        let expected_type = infer_fhir_type_from_path(&field_mapping.fhir_path);

        // Transform value
        let fhir_value = self.transform_engine.transform_to_fhir(
            db_value,
            field_mapping.transformation_id,
            expected_type,
        )?;

        // Set value using FHIR path
        let fhir_path = FhirPath::parse(&field_mapping.fhir_path)?;
        fhir_path.set(&mut fhir_resource, fhir_value)?;
    }

    // 4. Clean up empty objects in arrays
    clean_empty_objects(&mut fhir_resource);

    Ok(fhir_resource)
}

Result:

{
  "resourceType": "Patient",
  "id": "123",
  "active": true,              // Converted from TINYINT 1
  "identifier": [
    {"value": "12345678-9"}    // From rut_pac column
  ],
  "name": [{
    "family": "Garcia",        // From ap_pat_pac
    "given": ["Juan"]          // From nom_pac
  }],
  "gender": "male",            // Transformed from 'M'
  "birthDate": "1985-03-15"    // From fec_nac_pac
}

Edge Cases and Gotchas

1. Sparse Array Indices

When a mapping uses identifier[1].value, the path parser creates empty objects at [0]:

{
  "identifier": [{}, {"value": "X"}]  // ❌ Breaks deserialization
}

Solution: Clean empty objects after mapping:

fn clean_empty_objects(value: &mut JsonValue) {
    if let JsonValue::Array(arr) = value {
        arr.retain(|item| {
            if let JsonValue::Object(map) = item {
                !map.is_empty()  // Keep only non-empty objects
            } else {
                true
            }
        });
    }
    // Recurse into nested structures...
}

2. NULL Values

Database NULL ≠ JSON null. Omit the field entirely:

// Skip NULL values unless required
if matches!(db_value, DbValue::Null) {
    if field_mapping.is_required {
        return Err("Required field is NULL");
    }
    continue;  // Skip this field
}

3. Bidirectional Mapping

Creating a Patient means going FHIR → DB:

pub fn to_db(
    &self,
    resource_type: &str,
    fhir_resource: &JsonValue,
) -> Result<HashMap<String, DbValue>> {
    let mut db_row = HashMap::new();

    for field_mapping in field_mappings {
        let fhir_path = FhirPath::parse(&field_mapping.fhir_path)?;
        let fhir_value = fhir_path.get(fhir_resource)?;

        // Reverse transformation
        let db_value = self.transform_engine.transform_to_db(
            &fhir_value,
            field_mapping.transformation_id,
        )?;

        db_row.insert(field_mapping.database_column.clone(), db_value);
    }

    Ok(db_row)
}

Performance Considerations

The Good:

• Type inference is O(1) (string comparison)

• Path parsing is cached per-mapping

• Transformations are pure functions (no I/O)

The Tradeoff:

• Dynamic mapping is ~2x slower than hand-coded (15ms vs 8ms)

• But it means zero code for new tenants

• Worth it for our use case

Coming Up: Security and Observability

The mapping engine handles what data gets transformed. But we also need to know who accessed what data and when.

In Part 4, we'll cover:

• Authentication and authorization with Keycloak

• Audit logging for HIPAA compliance

• Rate limiting and circuit breakers

• Monitoring what matters

Discussion: How do you handle schema evolution in your systems? Code generation vs runtime configuration? Let me know your approach!

Imagine you're running a SaaS application. Now imagine that application handles the most sensitive data possible: medical records. Now imagine that a single bug could expose Patient A's cancer diagnosis to Hospital B.

That's the stakes we're playing with in a multi-tenant healthcare system.

Most SaaS apps solve multi-tenancy at the application layer—same database, different tenant_id columns. That works for Slack or Notion. It doesn't work for healthcare.

Here's why:

• Regulatory compliance: HIPAA requires strong data isolation

• Different schemas: Hospital A stores patient names as patient_name, Hospital B uses full_name

• Legacy systems: Each tenant runs their own ancient MySQL database on-premise

• Zero trust: One tenant's data must be physically impossible to access from another tenant's queries

The Architecture: Database-Level Isolation

Instead of logical isolation (same DB, different rows), I went with physical isolation—each tenant gets their own database connection to their own database.

// Each tenant has their own encrypted database URL
pub struct TenantDatabaseConfig {
    pub id: i32,
    pub client_id: String,
    pub database_url: String,  // Encrypted
    pub database_type: DatabaseType,
}

The Connection Pool Dance

Here's the tricky part: you can't create a new database connection for every request. Connections are expensive (100ms+ handshake). But you also can't keep 1000 connection pools open if you have 1000 tenants.

I built a TenantPoolManager that:

1. Lazily creates connection pools (only when needed)

2. Caches them in memory for fast access

3. Evicts idle pools after 30 minutes of inactivity

4. Validates connections before returning them

pub struct TenantPoolManager {
    pools: Arc<Mutex<HashMap<String, DatabasePool>>>,
    encryption_key: Vec<u8>,
}

impl TenantPoolManager {
    pub async fn get_pool(&self, client_id: &str) -> Result<DatabasePool> {
        // Check cache first
        {
            let pools = self.pools.lock().unwrap();
            if let Some(pool) = pools.get(client_id) {
                return Ok(pool.clone());
            }
        }

        // Not cached - fetch config, decrypt URL, create pool
        let config = self.fetch_tenant_config(client_id).await?;
        let decrypted_url = self.decrypt_database_url(&config.database_url)?;
        let pool = self.create_pool(&decrypted_url).await?;

        // Cache it
        let mut pools = self.pools.lock().unwrap();
        pools.insert(client_id.to_string(), pool.clone());

        Ok(pool)
    }
}

Encryption

Database URLs contain credentials. Storing them in plaintext would be... unwise.

Every tenant's database URL is encrypted using AES-256-GCM before hitting the database:

fn encrypt_database_url(&self, url: &str) -> Result<String> {
    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(&self.encryption_key));
    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);

    let ciphertext = cipher.encrypt(&nonce, url.as_bytes())
        .map_err(|e| AdapterError::Encryption(e.to_string()))?;

    // Encode as base64 for storage
    let mut combined = nonce.to_vec();
    combined.extend_from_slice(&ciphertext);
    Ok(base64::encode(&combined))
}

The encryption key lives in environment variables, never in the database.

Configuration Caching: Speed vs Consistency

Each tenant has a configuration:

• Which FHIR resources they support

• How to map FHIR paths to database columns

• Custom transformations (e.g., "1"/"0" → true/false)

• Nested array handling strategies

Loading this from MySQL on every request would be slow (5-10ms per query). But caching it forever means configuration changes don't take effect.

I built a ConfigResolver with a TTL-based cache:

pub struct ConfigResolver {
    cache: Arc<Mutex<HashMap<String, CachedConfig>>>,
    cache_ttl: Duration,
}

struct CachedConfig {
    config: TenantConfig,
    loaded_at: Instant,
}

impl ConfigResolver {
    pub async fn get_config(&self, client_id: &str) -> Result<TenantConfig> {
        // Check cache
        {
            let cache = self.cache.lock().unwrap();
            if let Some(cached) = cache.get(client_id) {
                if cached.loaded_at.elapsed() < self.cache_ttl {
                    return Ok(cached.config.clone());
                }
            }
        }

        // Cache miss or expired - reload
        let config = self.load_from_database(client_id).await?;

        let mut cache = self.cache.lock().unwrap();
        cache.insert(client_id.to_string(), CachedConfig {
            config: config.clone(),
            loaded_at: Instant::now(),
        });

        Ok(config)
    }

    // Admin panel calls this after configuration changes
    pub async fn invalidate(&self, client_id: &str) {
        let mut cache = self.cache.lock().unwrap();
        cache.remove(client_id);
    }
}

Authentication: Keycloak Integration

Multi-tenancy isn't just about data—it's about who can access that data.

I integrated Keycloak for enterprise SSO:

• Client ID embedded in JWT: Every request includes client_id claim

• Role-based access: fhir-read, fhir-write, fhir-admin

The authentication flow:

1. User logs in via Keycloak

2. Every request to the adapter includes this JWT

3. Middleware validates JWT and extracts client_id

4. All database queries are scoped to that client_id

Keycloak issues JWT with claims:

{
  "sub": "user-123",
  "client_id": "tenant-42",
  "realm_access": {
    "roles": ["fhir-read", "fhir-write"]
  }
}

No way to query across tenants. The client_id is the security boundary.

// Middleware that extracts and validates tenant context
pub async fn auth_middleware(
    State(state): State<AppState>,
    req: Request,
    next: Next,
) -> Result<Response, AppError> {
    let token = extract_bearer_token(&req)?;

    // Validate JWT signature and expiration
    let claims = state.keycloak.validate_token(&token).await?;

    // Extract client_id - this determines data isolation
    let client_id = claims.client_id
        .ok_or_else(|| AppError::Unauthorized("Missing client_id"))?;

    // Inject into request extensions for downstream handlers
    req.extensions_mut().insert(AuthContext {
        user_id: claims.sub,
        client_id,
        roles: claims.realm_access.roles,
    });

    Ok(next.run(req).await)
}

Lessons Learned

✅ What Worked

1. Database-level isolation: No worrying about leaked WHERE clauses

2. Lazy pool creation: Most tenants are idle most of the time

3. TTL-based config cache: 5-minute TTL is a sweet spot

❌ What Didn't

1. Initial design had no pool eviction: Memory grew unbounded

2. Encrypted URLs in logs: Accidentally logged encrypted URLs (look like gibberish, but still bad)

3. No circuit breakers: One tenant's broken DB took down the whole adapter

🔧 Improvements Made

1. Added pool eviction after 30 min idle

2. Sanitized all logging (URLs, credentials, PHI)

3. Per-tenant circuit breakers (now one tenant can fail without affecting others)

Up Next: The Mapping Engine

Physical isolation solves security. But how do we handle the fact that Hospital A stores patient names as patient_name while Hospital B uses nombre_paciente?

That's where the dynamic mapping engine comes in.

Part 3 will dive deep into how the adapter translates arbitrary database schemas into standard FHIR resources at runtime—without code generation.

Discussion: How do you handle multi-tenancy in your systems? Physical vs logical isolation? Let me know your thoughts.

Healthcare systems are a mess. I don't mean that lightly—after years of working with legacy hospital databases, I've seen it all: patient data stored in decades-old MySQL schemas (or even Microsoft Access), custom field names that made sense to someone in 1998, and zero interoperability between systems.

When a doctor needs to access a patient's complete medical history, they often can't. The data exists, scattered across multiple incompatible systems, each speaking its own dialect.

FHIR (Fast Healthcare Interoperability Resources) was supposed to solve this. It's a modern standard for exchanging healthcare information electronically. But there's a catch: most healthcare providers run on legacy systems that predate FHIR by decades.

The Solution: A Bridge Between Worlds

I decided to build a FHIR adapter—a system that sits between legacy databases and modern FHIR-based applications. It translates old-school database schemas into standard FHIR resources on the fly.

But here's where it gets interesting: this isn't just for one hospital. It's multi-tenant, meaning hundreds of healthcare organizations can use the same adapter instance, each with their own completely isolated data and custom database schemas.

Why Rust?

I'll be honest: I started from zero with Rust. No production experience, just curiosity and a belief that Rust was the right tool for this job.

Here's why I chose it:

1. Performance Matters in Healthcare

When a doctor requests a patient's records, they need them now. Not in 5 seconds, not after a loading spinner—now. Rust's zero-cost abstractions and performance characteristics meant I could build a system that handles thousands of requests per second without breaking a sweat.

2. Memory Safety Without Garbage Collection

Healthcare data is sensitive. A memory leak or buffer overflow isn't just a bug—it's a potential HIPAA violation. Rust's borrow checker guarantees memory safety at compile time, eliminating entire classes of vulnerabilities that plague C/C++ systems.

3. Fearless Concurrency

A multi-tenant system means handling hundreds of database connections simultaneously, each to different legacy databases. Rust's ownership model makes concurrent programming not just possible, but safe and predictable.

// This is legal Rust - the compiler guarantees safety
async fn handle_request(tenant_id: &str) -> Result<Patient> {
    let pool = tenant_pool_manager.get_pool(tenant_id).await?;
    let config = config_resolver.get_config(tenant_id).await?;

    // Multiple async operations, all safe
    let patient = fetch_patient(&pool, &config).await?;
    Ok(patient)
}

4. Learning Curve as a Feature

Yes, Rust is hard. The borrow checker will fight you. You'll spend hours debugging lifetime errors. But here's the thing: every error you fix at compile time is a bug that won't crash in production.

The Tech Stack

After evaluating options, here's what I landed on:

• Backend: Rust + Axum (web framework)

• Database: MySQL (for adapter config) + dynamic connections to tenant databases

• Authentication: Keycloak (enterprise SSO)

• Admin Panel: Next.js 14 + TypeScript

• Deployment: Docker + systemd

Early Decisions That Mattered

Decision 1: Dynamic Configuration Over Code Generation

Instead of generating code for each tenant's schema, I built a dynamic mapping engine that reads configuration at runtime. This means:

• ✅ No recompilation needed when onboarding a new tenant

• ✅ Tenant admins can configure mappings via UI

• ❌ More complex runtime logic

Decision 2: Compile-Time Safety Where Possible, Runtime Flexibility Where Needed

I used Rust's type system aggressively for the core adapter logic, but accepted serde_json::Value for the dynamic mapping layer. The tradeoff was worth it.

Decision 3: Admin Panel in TypeScript, Not Rust

I could have built the admin UI in Rust (Yew, Leptos, etc.), but Next.js was the pragmatic choice. Development velocity matters, and React's ecosystem is unmatched for building complex forms.

What's Coming Next

In the next posts, I'll dive deeper into:

• Part 2: Multi-tenant architecture and database isolation

• Part 3: The dynamic mapping engine that powers it all

• Part 4: Security, authentication, and audit logging

• Part 5: Building an admin panel that doesn't suck

Starting from Zero

When I started this project, I had:

• Zero production Rust experience

• A vague understanding of FHIR

• A belief that healthcare IT could be better

Six months later, I have:

• A working multi-tenant FHIR adapter

• 20,000+ lines of Rust

• Battle scars from fighting the borrow checker (and winning)

If you're considering Rust for a production project, here's my advice: do it. The learning curve is steep, but the payoff is real. You'll write better code, catch bugs earlier, and sleep better knowing your production system won't randomly segfault at 3 AM.

This is Part 1 of a 5-part series documenting my journey building a multi-tenant FHIR adapter from scratch. Follow along at compile.care for updates.