Skip to content

architecture.md

Latest commit

 

History

History
135 lines (114 loc) · 8.67 KB

architecture.md

File metadata and controls

135 lines (114 loc) · 8.67 KB
Raw

Architecture

Tula runs on a single self-hosted VM. The OpenClaw gateway routes user input (Telegram, email, and future voice) into Tula skills that read and write a private workspace memory layer. Continuous evaluation runs via Microsoft Waza in CI. Model routing is deployment-context-aware across Microsoft, OpenAI, Anthropic, Google, xAI, Mistral, DeepSeek, Cohere, and open-weight backends.

This page is the canonical architecture reference for the open-source Tula reference deployment. The hospital-scale commercial extension is described in docs/aria-commercial-platform.md.

Component diagram

The diagram below distinguishes live components (deployed and ready on the reference VM) from planned components (on the roadmap). The docs/roadmap.md page is the canonical source of truth for individual component states.

User Interface
  |-- Telegram                                   (live)
  |-- Email outbound                             (live)
  |-- Email inbound auto-ingest                  (in progress)
  |-- Voice calls (Twilio + voice-call plugin)   (plan documented)
        |
Data Sources
  |-- Live
  |     |-- Patient portals via SMART on FHIR    -> health-records skill (via Wren relay)
  |     |-- Medical PDFs (lab, imaging, OCR)     -> med-pdf skill
  |     |-- X (Twitter) search                   -> @openclaw/xai-plugin
  |     |-- Brave web search                     -> @openclaw/brave-plugin
  |-- Planned
        |-- Email inbox auto-classify            (M365 / Graph API)
        |-- Wearables (Garmin, Oura, Whoop, Withings, Apple Health)
        |-- Home devices (BP, scale, pulse ox, glucose)
        |-- Genomic reports (23andMe, AncestryDNA)
        |-- Research feeds (PubMed, Google Scholar)
        |
OpenClaw Gateway  -- single self-hosted VM (Azure B2s, Ubuntu 24.04, ~$30/mo)
        |
Tula Skills  -- deployed under ~/.openclaw/workspace/skills/
  |-- Live (this repo, ready on reference VM)
  |     |-- health-records   -- SMART on FHIR records pull (via Wren relay)
  |     |-- med-pdf          -- PDF to structured labs, imaging JSON
  |     |-- epic-note        -- draft portal messages to clinicians
  |     |-- myhealth-pulse   -- signal aggregation orchestrator
  |     |-- memory-diff      -- longitudinal change detection
  |     |-- prep-my-visit    -- IPS-aligned visit-prep package
  |     |-- request-amendment-- HIPAA-aligned record amendment requests
  |     |-- lookout          -- ambient environmental / public-health awareness
  |-- Planned
        |-- email-router     -- inbound classification and routing
        |-- lab-parser       -- structured biomarker tracker beyond med-pdf
        |-- patient-journal  -- Telegram daily check-ins
        |-- professional-journal
        |-- wearable-sync    -- one adapter per device family
        |-- home-device-sync -- BP, scale, pulse ox, glucose
        |-- genomic-analyzer
        |-- medical-image-interpreter -- DICOM (MedGemma / MedImageInsight)
        |-- de-identification-engine  -- HIPAA Safe Harbor
        |-- research-synthesis        -- PubMed / Google Scholar summarization
        |
Self-Hostable Services  -- this repo, under services/
  |-- wren  -- single-tenant SMART on FHIR records relay; backs health-records.
  |           Set HEALTH_SKILLZ_BASE_URL to self-host instead of a third-party host.
  |           MIT derivative of jmandel/health-skillz. Multi-tenant version is Aria.
        |
Agent Workspace Memory  -- ~/.openclaw/workspace/
  |-- MEMORY.md            -- persistent state (conditions, meds, providers, trends)
  |-- memory/YYYY-MM-DD.md -- dated agent notes
  |-- memory/profile.yaml  -- personalization profile (read by myhealth-pulse, etc.)
  |-- .health-records-cache/<date>/<provider>.json   -- FHIR R4 pulls
  |-- .med-pdf-cache/<slug>/                         -- PDF extractions
  |-- .myhealth-pulse-cache/<date>.json              -- pulse digests
  |-- .memory-diff-cache/<date>.md                   -- diff renderings
        |
Continuous Evaluation and Compliance  -- Microsoft Waza, this repo
  |-- evals/<skill>/eval.yaml + tasks/ + fixtures/   (open eval suites)
  |-- waza check         -- static compliance gate on every PR via CI
  |-- docs/evals.md      -- continuous status, regenerated by CI on every push
  |-- waza run (local)   -- live LLM execution; results/ gitignored
        |
AI Model Routing  -- deployment-context-aware; see docs/model-routing.md
  |-- Reference deployment today
  |     |-- Clinical reasoning: Claude Sonnet 4.6 (Anthropic, via copilot-sdk)
  |     |-- General tasks: gpt-4o-mini (OpenAI, via copilot-sdk)
  |-- First-class supported providers
  |     |-- Microsoft: Azure AI Foundry, Azure OpenAI, Azure Speech, MedASR
  |     |-- OpenAI:    GPT family, o-series reasoning, Whisper
  |     |-- Anthropic: Claude family (direct API or via Azure AI Foundry)
  |-- Other SOTA providers OpenClaw can route to
  |     |-- Google (Gemini, Gemini Live for voice), xAI (Grok), Mistral,
  |     |   DeepSeek, Cohere, Cerebras, Together, Fireworks, open-weight
  |     |   models via vLLM, and many more through the OpenClaw plugin system
  |-- Planned healthcare-specific routing
        |-- Voice loop: Gemini Live (via @openclaw/voice-call plugin)
        |-- Medical text: MedGemma 27B / Claude in Azure AI Foundry
        |-- Medical imaging: MedGemma 4B / MedImageInsight / CXRReportGen
        |-- Medical speech: MedASR / Azure Speech Services

Skill composition

The live skills produce structured outputs (FHIR R4 JSON, extracted lab and imaging JSON, rendered digests) that land in the workspace memory layer. Other skills consume what is already there rather than re-fetching:

  • health-records pulls through the self-hostable Wren relay, so a deployment can run the entire records-pull path with no third-party dependency.
  • memory-diff reads from the cache directories health-records and med-pdf write to.
  • myhealth-pulse writes its own daily cache that memory-diff includes in its scan.
  • epic-note composes a draft portal message using context from MEMORY.md and the latest cache outputs without forcing the user to paste anything in.
  • prep-my-visit and request-amendment assemble visit-prep packages and amendment-request drafts from the same workspace memory, never re-fetching from the portal.

This composition is intentional and is what makes the agent feel like it knows you over time rather than like a transactional chatbot.

Self-hosting

The reference deployment runs on a single self-hosted VM (Azure B2s, 2 vCPU, 4 GB RAM, Ubuntu 24.04, roughly $30 per month). Health data stays on the user's own server. No cloud health platforms. No third-party data sharing.

The full self-host walkthrough is in docs/deployment-guide.md. The deployment guide was written during a real setup session and documents the actual experience, including common errors and their solutions.

Continuous evaluation

Every skill ships an open evaluation suite under evals/<skill>/ with task fixtures, ground truth, and a Waza spec gate enforced in CI on every PR. The static spec gate (schema, link integrity, token budget, advisory checks) catches structural regressions before they merge. The live-LLM run (waza run) is executed locally against a real model, with results gitignored to keep the repo clean of provider-specific output. The continuous compliance status is regenerated at docs/evals.md.

Detail on the open-versus-closed evaluation boundary is in docs/aria-commercial-platform.md.

Model routing

Routing is deployment-context-aware: each task is directed to the most capable, cost-effective, and privacy-appropriate model available in that foundry, in that deployment, at that moment. See docs/model-routing.md.

Security model

Email ingestion is locked to authorized senders at the Exchange transport layer. Outbound email is restricted to authorized recipients. Prompt injection risks are analyzed honestly and mitigated at multiple layers. See docs/security-model.md.

See also