Skip to content

Overview

  • :material-shield-check:{ .lg .middle } Core Services

    Canonical, Storage, Messaging, Gateway — secure and modular

  • :material-puzzle:{ .lg .middle } Modular Design

    Plugin-first architecture with well-defined contracts

  • :material-insights:{ .lg .middle } Observability

    Audit logs, metrics, and health endpoints across services

Admin-First Design

All core service operations must be available through the Admin Console. No CLI-only controls.

PHI/PII Handling

Core services are built to minimize PHI exposure. Use classification and redaction in storage and messages.

Network Exposure

Do not expose internal core endpoints directly to the public internet. Use the Gateway for external access.

Services at a Glance

Service Purpose Exposed Interfaces HIPAA
canonical Normalize and transform data gRPC/REST, plugins Compliant
storage Encrypted PHI/PII storage REST API, SDK Compliant
messaging Inter-plugin event bus Pub/Sub API Compliant
gateway External proxy & filtering HTTP(S) ingress Compliant

  • :material-code-tags-check:{ .lg .middle } Stable SDKs

    Python and Node.js SDKs for service access

  • :material-security:{ .lg .middle } Audit & Retention

    7-year retention for audit logs, tamper-proof append-only store

High-level Architecture

mermaid flowchart LR AdminUI[Admin Console] -->|Admin API| API[Admin API Gateway] API --> Canonical[Canonical Service] API --> Storage[Storage Service] API --> Messaging[Messaging Service] Gateway[External Gateway] -->|Proxied Requests| API Storage -->|Encrypted| Vault[(Key Vault)]

Getting Service Status

# (1) Simple health check against Admin API
import requests
r = requests.get('https://localhost:8443/health')
print(r.json())

// (1) Node health check
const fetch = require('node-fetch')
fetch('https://localhost:8443/health').then(r => r.json()).then(console.log)

# (1) Use curl to check overall platform health
curl -sS https://localhost:8443/health | jq
  1. Requests the unified health endpoint which aggregates service health

Service Contracts (short)

  • Canonical: accepts plugin-specific payloads, returns normalized canonical model
  • Storage: uses AES-256 at rest, per-tenant keying supported
  • Messaging: event bus supports routing, filters, and PII-safe payloads
  • Gateway: domain allowlists, request/response transformations

Operator Lane & Messaging — What You Need To Do

  • Ensure plugins expose an inbox endpoint
  • Add an endpoint key in the plugin manifest: message.receive (or messages.receive, inbox, or message) pointing to your handler path, e.g., /inbox.
  • The Core dispatcher will POST messages to that path with X-Caller-Plugin and optional Authorization header (plugin token).
  • Configure operator allowlists
  • Use POST /admin/operator/allowlist/auto-generate with { caller, target, merge: true } to seed operations from the target plugin’s manifest endpoints.
  • Edit or review via Admin Console → Operator Policy.
  • Optional dev-mode: allow manifest-declared operations without explicit allowlist by setting DEV_MODE=true or operator.allow.dev_all=true (ConfigService).
  • Optional tuning via env
  • MESSAGE_MAX_ATTEMPTS, MESSAGE_RETRY_BASE_SECONDS, MESSAGE_DELIVERY_TIMEOUT for delivery retry/backoff.
  • EVENT_BUS_BACKEND = memory | nats | redis to select event bus transport.

Glossary

CanonicalUser
Standard user model across plugins
Audit Log
Immutable, append-only record of data and operational events

Operational Checklist

  • Ensure audit.retention_years >= 7
  • Verify encryption keys stored in Key Vault
  • Regularly rotate keys and review RBAC
Debugging Tips

Use Ctrl+Shift+I to open browser devtools for Admin UI troubleshooting. Check network requests to /api/* endpoints.