Arquitectura

Arquitectura de capas

Estructura de carpetas

emafhir/
├── src/
│   ├── index.ts              # Public API (5 grupos de exports)
│   ├── core/                 # FhirClient genérico (compat pre-Wave 1)
│   ├── ema-client.ts         # EmaFhirClient (extends FhirClient)
│   ├── profile-resolver.ts   # ProfileResolver (Supabase runtime)
│   ├── meta-injection.ts     # injectMeta async idempotente
│   ├── translate.ts          # applyAutoTranslate (opt-in $translate)
│   ├── auth/                 # clientCredentials, bearerAuth
│   ├── search/               # SearchBuilder fluent
│   ├── validators/           # RUN, CURP, RFC, DNI
│   ├── types/                # FHIR R4 + Tenant + ResourceTypeMap
│   ├── sdc/                  # Questionnaire renderer headless
│   ├── react/                # SDC hooks (useSDCForm)
│   └── helpers.ts            # ref, transaction
├── docs/
│   ├── decisions.md          # F001-F054
│   ├── adr/                  # ADRs formales
│   └── CHANGELOG.md
└── tests/

Flujo de un write con auto-inyección

API pública

import {
  // Factory clients
  createClient,        // legacy: FhirClient genérico
  createEmaClient,     // Wave 1+: EmaFhirClient con tenant + Supabase

  // Resolver y meta
  ProfileResolver,
  injectMeta,
  applyAutoTranslate,

  // Helpers
  ref,
  transaction,
  search,

  // Auth
  clientCredentials,
  bearerAuth,
} from 'emafhir';

import {
  validateRun,
  validateCurp,
  validateRfc,
  validateDni,
} from 'emafhir/validators';

Refactor reciente — antes vs después

Antes	Después
src/data/countries.ts mirror estático	ProfileResolver lee Supabase runtime
Cada cambio de país requería bump de SDK	Cambio en Vault → SDK lo refleja en ≤ 5 min
Test test:countries-sync guard CI	Test smoke contra Aidbox edge (T7)
Productos pinneaban versión exacta	Productos no requieren cambios al actualizar países
Hardcoded en build	Lazy + cache + dedup de promesas concurrentes

Migración Wave 3 pendiente

emalab, emavault y emawell todavía usan createClient() legacy. Cuando se ejecuten sus refactors, deben migrar a createEmaClient({ tenant, supabase }) y agregar la peer dep de Supabase.

Política de createClient legacy

createClient() y la FhirClient core siguen exportados y soportados en 0.6.x — no son deprecated. Los productos pre-Wave 1 los usan directamente y no van a romperse al bumpear el SDK.

Cuándo migrar:

• Recomendado: durante el refactor del producto correspondiente (Wave 3 del Plan Consolidado), porque ahí ya tocás el código que llama a Aidbox.
• No urgente: si tu producto no necesita meta-inyección automática ni ProfileResolver runtime, podés seguir con createClient() indefinidamente. La API legacy no tiene fecha de remoción.

Cuándo se va a deprecar:

• En 1.0.0, createClient queda con @deprecated JSDoc.
• En 2.0.0, se remueve. Esto está fuera del horizonte del Plan Consolidado.