Skip to main content

Requirements Guard Rails — Architecture, Compliance, Interoperability

Purpose: Cross-cutting guard rails for new requirements work, spec refreshes, and AI-assisted generation.
Authority: Normative together with ARCHITECTURE_BASELINE.md, MODULE_SHARED_STANDARDS.md, and COMPLIANCE_SECURITY.md. If a statement here conflicts with those baselines, the baseline documents in specs/architecture/ win unless explicitly revised.

Architecture and stack​

  1. Target architecture

    • Microservices and domain-driven design (DDD).
    • API edge: Kong (or Kong Gateway) as the single public HTTP entry for browser clients and partner integrations — routes to NestJS upstreams, TLS termination, authentication plugins aligned with IAM (e.g. JWT/OIDC validation), rate limiting, request size limits, correlation/request IDs for tracing, and optional bot/WAF plugins. Internal service-to-service traffic may bypass Kong on a private network per deployment policy, but browser and external API consumers MUST NOT call NestJS services directly on the public internet in production.
    • Backend: NestJS services, NATS JetStream for messaging.
    • Client / persistence: Technology-agnostic data layer to support offline-first local stores (e.g. Realm, Couchbase Lite, SQLite, Ditto) or PostgreSQL (and equivalents), configurable per product surface and deployment. Afghanistan-first and similar low-connectivity contexts prioritize offline-capable clients with bidirectional sync where policy allows.
    • AI foundation: Assistive AI (documentation, speech-to-text, coding assist, etc.) is a platform concern via ai-orchestrator behind Kong; see AI_PLATFORM.md and FR-AI-### in specs/core/EHR_FUNCTIONAL_REQUIREMENTS.md. All such features MUST be license-gated, auditable, and privacy-reviewed.
    • Frontend: Next.js (App Router), MUI + Emotion.
    • All browser portals: MUST build on the licensed Berry (CodedThemes) template—components, styles, and license-permitted resources—as the shared UI foundation; apps/ehr-web is the canonical surface for clinician shells and dense dashboards (see FRONTEND_BERRY_TEMPLATE_REFERENCE.md and docs/widget/BERRY_TEMPLATE_REQUIREMENT.md).
    • Multi-tenant, cloud-native, containerized (Docker/Kubernetes), with on-prem deployment support.
    • Offline-first where applicable: critical workflows MUST degrade gracefully and synchronize when online (see OFFLINE_FIRST_AND_CLIENT_SYNC.md).
    • Caching and indexing MUST be explicitly considered (Redis or equivalent, database indexes).

  2. Every requirement set MUST

    • Respect bounded contexts and aggregates (DDD).
    • Clearly distinguish core platform modules vs add-ons licensed via the Licensing service.
    • Support a DAG-based configuration model for organization / tenant hierarchy (configurable roots: public vs private institutions, hospitals, sites, departments, wards, clinics, practices, etc.).
    • Support multi-tenancy (data isolation, configuration per tenant, safe cross-tenant boundaries).
    • Assume containerized deployment and twelve-factor app principles.

  3. Frontend requirements MUST

    • Use Next.js (App Router) and MUI + Emotion.
    • For all portal frontends, follow the licensed Berry template (components, theme/styles, patterns); apps/ehr-web carries the canonical clinician ui-component shell—do not replace with ad-hoc dashboard or app chrome (see FRONTEND_BERRY_TEMPLATE_REFERENCE.md).
    • Support a configurable design system per hierarchy level (platform, tenant, org node) for white-labeling: themes, logos, typography, components, design tokens, and token presets where product policy defines them.
    • Support multiple IAM providers (Keycloak, Okta, Auth0, etc.) via OIDC/OAuth2 (and SAML where needed).
    • Support multilingual UI (i18n) with LTR and RTL layouts (see REGIONAL_PROFILE.md).
    • Consider offline-first UX where relevant (local cache, sync status, conflict surfacing).

Compliance, security, interoperability​

  1. All requirements MUST consider

    • Security: OWASP ASVS, zero-trust principles (aligned with COMPLIANCE_SECURITY.md).
    • Privacy and data protection: HIPAA, PHIPA, GDPR, ISO 27701 (where applicable).
    • Information security: ISO 27001, NIST CSF.
    • Healthcare standards: HL7 v2, HL7 FHIR, DICOM (if imaging), ICD-10/11, LOINC, SNOMED CT (where licensed).
    • Governance and safety: WHO digital health guidance, local MoH regulations.

  2. For every module, compliance-oriented requirements SHOULD identify

    • PHI/PII data elements.
    • RBAC/ABAC rules.
    • Audit logging, retention, and deletion rules.
    • Encryption in transit (TLS 1.2+) and at rest (AES-256 or equivalent).
    • Interoperability expectations (FHIR resources, profiles, terminology bindings).
    • Data residency and cross-border transfers where applicable.

  3. Definition of “complete” for a requirement

    • Explicit architecture, compliance, and interoperability considerations where relevant.
    • Traceability to at least one control framework or system FR/NFR where applicable (see module TRACEABILITY_MATRIX.md).

Engineering quality​

  • Backend and frontend code SHOULD maintain ≥80% automated test coverage unless a baseline document specifies otherwise.
  • Coverage includes: unit tests, integration tests, contract tests, sync/offline-first tests where the module supports disconnected use, and E2E tests where UI exists.
  • Critical modules (identity, registration, orders, medications, billing, and similarly safety-critical domains) SHOULD target ≥90% where the testing standards document requires it.
  • Microservices SHOULD include:
    • Unit tests (NestJS).
    • Integration tests (PostgreSQL and/or offline-first store as applicable).
    • Contract tests: HTTP through Kong for routes exposed to clients/partners, plus NATS contracts as applicable.
    • E2E tests (Next.js) for critical flows.
  • Coverage SHOULD be enforced via CI/CD gates per TESTING_STANDARDS.md.
DocumentRole
ARCHITECTURE_BASELINE.mdSystem architecture — authoritative
OFFLINE_FIRST_AND_CLIENT_SYNC.mdClient sync and offline patterns
MODULE_SHARED_STANDARDS.mdPer-module shared rules
EHR_FUNCTIONAL_REQUIREMENTS.mdSystem-level FR/NFR (incl. FR-AI, FR-NFR-015..018)
AI_PLATFORM.mdAI orchestration, policy, events, safety boundary
specs/_generation/README.mdPrompts for spec generation and implementation alignment