Skip to main content

Module Shared Standards

Purpose: This document defines cross-cutting standards that apply to every Ghasi EHR module. Module-specific SPEC.md, SOLUTION_DESIGN.md, EVENT_MODEL.md, and TECHNICAL_REQUIREMENTS.md files reference this document instead of repeating these paragraphs. When implementing any module, load this file once and apply its rules universally.

1. Licensing & Activation Gate​

Every module shall respect tenant/facility-scoped licensing and activation at runtime:

  • When unlicensed or disabled, module UI entry points are hidden and module APIs reject requests with HTTP 403 and error code MODULE_NOT_LICENSED.
  • Deactivation preserves historical data per retention/policy.
  • Reference: EHR_FUNCTIONAL_REQUIREMENTS.md FR-MOD-003..007.

Implementation pattern:

  • Backend: LicensingGuard (NestJS guard) checks tenant entitlements from Redis cache before every controller method.
  • Frontend: Shell navigation and route guards query the licensing API; unlicensed modules are omitted from menus and return a "Module not available" placeholder if navigated to directly.

2. HMIS / Ecosystem Interoperability​

Every module's clinical or administrative data shall be exchangeable with external HMIS/EHR/HIE systems through the platform's standards-based integration layer:

  • FHIR R4+ interface (primary)
  • HL7 v2 where applicable (via hl7v2-interop adapters)
  • X12 for insurance/claims domains
  • CDA for document exchange where required
  • Configurable adapter-based integrations for non-standard endpoints

Reference: EHR_FUNCTIONAL_REQUIREMENTS.md FR-INT-006..012.

Module-specific details: Each module's SPEC.md §6 (Interoperability) defines which FHIR resources, HL7 v2 message types, and adapter protocols apply. The shared pattern above applies to all.

3. Compliance — Consent & Disclosure Controls​

Every module shall:

  • Enforce consent/disclosure controls for data exports and integrations where configured.
  • Support accounting of disclosures where required by policy or regulation.
  • Respect "minimum necessary" data exposure rules for patient-facing and external interfaces.
  • Emit audit events for every access, mutation, export, and disclosure action.

Reference: EHR_FUNCTIONAL_REQUIREMENTS.md FR-COMP-011..013.

See also: COMPLIANCE_SECURITY.md.

4. Regional Localization (Phase 1: AFG / UAE)​

All modules operate under the Phase 1 regional/localization profile:

  • Languages: English (LTR), Pashto, Dari, Arabic (RTL).
  • UI direction: All module UIs, rendered documents (HTML/PDF/print), and labels shall support both LTR and RTL with correct mixed-direction rendering (identifiers, codes, units, dates, numeric values).
  • Calendar: Gregorian (primary), Hijri Shamsi / Hijri Qamari (display alongside).
  • Currency: AFN, AED (billing/insurance modules).
  • Identifiers: Afghan Tazkira, Emirates ID, MRN.

Reference: REGIONAL_PROFILE_AFG_UAE.md.

Implementation pattern:

  • Use MUI theme direction prop + Emotion RTL plugin.
  • Wrap numeric/code values in <bdi> or dir="auto" spans.
  • Store locale preference per user; default from tenant config.

5. Event Model Conventions​

5.1 Transport & Envelope​

PropertyValue
TransportNATS JetStream
EnvelopeCloudEvents v1.0
Subject patternghasi.{service-name}.{resource}.{verb}
Sourceghasi/{service-name}
DLQEvery stream must have a Dead Letter Queue configured

5.2 CloudEvents Minimum Fields​

Every event published by any module must include these CloudEvents attributes:

{
  "specversion": "1.0",
  "type": "ghasi.{service}.{resource}.{verb}",
  "source": "ghasi/{service-name}",
  "id": "<uuid>",
  "time": "<ISO-8601>",
  "tenantid": "<uuid>",
  "actorid": "<uuid>",
  "correlationid": "<uuid>",
  "data": { }
}
  • Use CloudEventsBuilder from @ghasi/nats-client to construct envelopes.
  • Module EVENT_MODEL.md files only need to document the **data payload** for each event type, not the full envelope.

5.3 Standard Event Verbs​

VerbMeaning
createdNew resource persisted
updatedResource mutated
deletedResource soft-deleted or removed
status.changedLifecycle state transition
archivedResource archived/deactivated

Modules may define additional domain-specific verbs (e.g., signed, acknowledged, overridden).

6. Audit Requirements​

Every module must:

  • Emit audit events on every mutation (create, update, delete, status change) via @ghasi/audit-client.
  • Include tenantId, actorId, resourceType, resourceId, action, and timestamp in every audit entry.
  • Log read access to sensitive data categories (clinical notes, results, medications).
  • Record FHIR/HL7/external API access events separately for accouvnting of disclosures.
  • Retain audit logs for minimum 7 years per compliance policy.

Reference: COMPLIANCE_SECURITY.md §3.

7. Multi-Tenancy & Data Isolation​

Every module must:

  • Scope all queries by tenantId — no cross-tenant data leakage.
  • Extract tenantId from JWT claims (not request body/query/headers).
  • Apply TenantGuard at the controller level.
  • Use Row-Level Security (RLS) or application-level scoping on every database query.

Reference: ARCHITECTURE_BASELINE.md §2.

8. Authentication & Authorization​

Every module must:

  • Require valid JWT bearer token (Keycloak OIDC) on all API endpoints.
  • Apply @Roles() decorators with appropriate role requirements per endpoint.
  • Use RolesGuard + @Roles() — never apply the guard without decorators.
  • Respect facility-level access when applicable (e.g., a provider at Facility A cannot access Facility B data).

Reference: ARCHITECTURE_BASELINE.md §5, COMPLIANCE_SECURITY.md.

Every module documentation set includes these files (relative to the module folder):

FilePurpose
SPEC.mdFunctional specification — requirements, business rules, scope
SOLUTION_DESIGN.mdData model, API specs, FHIR mappings, integration points
EVENT_MODEL.mdNATS event types with data payloads (envelope per §5 above)
TECHNICAL_REQUIREMENTS.mdArchitecture assumptions, API contracts, security/perf targets
TRACEABILITY_MATRIX.mdFR → API → Event → Test mapping
API_DOCS.mdOpenAPI-style endpoint documentation

Platform-level references that apply to all modules:

DocumentPath
Architecture Baselinespecs/architecture/baseline/ARCHITECTURE_BASELINE.md
Solution Design Baselinespecs/architecture/baseline/SOLUTION_DESIGN_BASELINE.md
Coding Standardsspecs/architecture/baseline/CODING_STANDARDS.md
Testing Standardsspecs/architecture/baseline/TESTING_STANDARDS.md
Technology Stackspecs/architecture/platform/TECHNOLOGY_STACK.md
FHIR-First Standardspecs/architecture/platform/FHIR_FIRST_STANDARD.md
Regional Profilespecs/architecture/platform/REGIONAL_PROFILE.md
Compliance & Securityspecs/architecture/platform/COMPLIANCE_SECURITY.md
Requirements guard railsspecs/architecture/platform/REQUIREMENTS_GUARD_RAILS.md
Offline-first & syncspecs/architecture/platform/OFFLINE_FIRST_AND_CLIENT_SYNC.md
AI platformspecs/architecture/platform/AI_PLATFORM.md
This documentspecs/architecture/baseline/MODULE_SHARED_STANDARDS.md

10. FHIR-First Architecture (Per-Module)​

Every module that owns clinical or administrative data must:

  • Define a canonical FHIR resource mapping (e.g., Vitals → Observation(vital-signs), Problems → Condition).
  • Expose FHIR read/search endpoints via the fhir-gateway.
  • Use the standard FHIR status mappings defined in FHIR_FIRST_STANDARD.md.
  • Store data in a structure that can be losslessly mapped to/from FHIR resources.

The specific FHIR resource(s) each module owns are listed in its SPEC.md §6 (Interoperability) and SOLUTION_DESIGN.md §2.1/§3.2.

11. Performance Baseline (Defaults)​

Unless a module's SPEC.md defines stricter targets:

MetricDefault Target
API p95 response time (reads)< 200 ms
API p95 response time (writes)< 400 ms
NATS event publish latency p95< 50 ms
Service availability99.9%
Data retention (audit)7 years minimum
PII encryption at restRequired

12. Offline-First and Synchronized Clients​

Modules that support disconnected or intermittent operation MUST document in SPEC.md and TECHNICAL_REQUIREMENTS.md:

  • Which workflows are offline-capable vs server-only.
  • Client mutation identity / idempotency expectations (e.g. clientMutationId, Idempotency-Key).
  • Conflict handling and user-visible resolution.
  • Audit obligations for queued actions and sync resolution.

Platform-wide patterns are normative in OFFLINE_FIRST_AND_CLIENT_SYNC.md. Clients MUST NOT violate tenant isolation when buffering data locally.

13. AI and Assistive Features​

Every module MUST state in SPEC.md (and update TRACEABILITY_MATRIX.md):

  • Whether it invokes AI, consumes orchestrator output, or supplies data to RAG/retrieval.
  • Which modes apply (per AI_PLATFORM.md §3): documentation assist, STT, coding assist, analytics, patient-facing, etc.
  • Audit events emitted (or consumed) for FR-AI-006 alignment.
  • Offline behavior for that module’s AI features (FR-AI-008).

Modules with no AI surface may state: “No direct AI orchestration; inherits platform defaults only.”

14. OpenAPI (Swagger) for HTTP services​

Every new NestJS (or HTTP) microservice under apps/services/* MUST expose machine-readable API documentation:

  • OpenAPI 3 via @nestjs/swagger: DocumentBuilder, SwaggerModule.setup, with a stable UI path (platform convention: api/docs on the service’s listen port unless an existing service in the same repo already documents a different path).
  • Controllers MUST use @ApiTags, @ApiOperation where the route is not self-explanatory, and @ApiBearerAuth() (or the correct security decorator matching the service’s auth scheme) on protected routes.
  • Request/response bodies MUST be documented with DTO classes using @ApiProperty / @ApiPropertyOptional (aligned with class-validator where used), or explicit @ApiBody / @ApiOkResponse schemas for FHIR/resource JSON where DTOs are not used.
  • The OpenAPI description SHOULD point to this module’s SPEC.md, API_DOCS.md, or specs/modules/<module>/ for integrators.

Evidence: Existing services (e.g. pharmacy, registration, tenant) follow this pattern; new services must match or exceed their documentation depth.

Usage note for AI models: Load this file once at the start of any module implementation session. Do not re-read the licensing, interop, compliance, regional, event, or audit sections from individual module specs — they are defined here. Module specs contain only domain-specific requirements, business rules, and data models.