# watson-assists/watson architecture

> Architecture diagram of the GitHub repository watson-assists/watson, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/watson-assists/watson
- Repository: https://github.com/watson-assists/watson

## Overview

Watson is a consultation-documentation product for integrative-care practitioners. Its main workflow is recording consultation audio, producing a transcript for practitioner review, and filling a structured form; the README notes that the engine is currently single-track. The wider product also includes patient booking and sign-in, documents, payments, Google Calendar, and WhatsApp. The graph includes those documented capabilities, but unsampled implementation links are omitted. Internal edges are limited to relationships visible in excerpts or the source index.

Main entry points: [`apps/clinical-worker/src/clinical_worker/engine.py`](https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/engine.py) (Job Engine), [`supabase/functions/patient-otp/index.ts`](https://github.com/watson-assists/watson/blob/main/supabase/functions/patient-otp/index.ts) (Patient OTP), [`apps/whatsapp-gateway/server.mjs`](https://github.com/watson-assists/watson/blob/main/apps/whatsapp-gateway/server.mjs) (WhatsApp Gateway), [`supabase/functions/_shared/server.ts`](https://github.com/watson-assists/watson/blob/main/supabase/functions/_shared/server.ts) (Edge Function Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Practitioner and Patient Web"]
  node_webapp["Watson Web App"]
  node_consultation["Consultation Workspace<br/>[page.tsx]"]
  node_booking["Booking<br/>[page.tsx]"]
  node_formwork["Form Review<br/>[page.tsx]"]
  node_patientjoin["Patient Join<br/>[page.tsx]"]
  node_webengine["Engine Status<br/>[engine.ts]"]
  node_dbtypes["Database Types<br/>[database.types.ts]"]
end

subgraph group_engine["Clinical Processing"]
  node_workercli["Worker CLI<br/>[__main__.py]"]
  node_jobengine["Job Engine<br/>[engine.py]"]
  node_audio["Audio Handling<br/>[audio.py]"]
  node_transcription["Transcription<br/>[transcribe.py]"]
  node_merge["Transcript Merge<br/>[merge.py]"]
  node_formfill["Form Filling<br/>[form.py]"]
  node_documents["Document Processing<br/>[documents.py]"]
  node_schema["Output Schema<br/>[schema.py]"]
end

subgraph group_platform["Supabase Platform"]
  node_supabase[("Supabase Database<br/>[supabase.ts]")]
  node_edgecommon["Edge Function Server<br/>[server.ts]"]
  node_otp["Patient OTP<br/>[index.ts]"]
  node_googlefn["Google Calendar Function<br/>[index.ts]"]
  node_paymentfn["Payment Function<br/>[index.ts]"]
  node_cleanup["Document Cleanup<br/>[index.ts]"]
end

subgraph group_messaging["WhatsApp Messaging"]
  node_whatsappfn["WhatsApp Function<br/>[index.ts]"]
  node_messages["Message Wording<br/>[messages.ts]"]
  node_gateway["WhatsApp Gateway<br/>[server.mjs]"]
  node_sealed["Pairing Encryption<br/>[sealed.mjs]"]
end

subgraph group_integrations["External Integrations"]
  node_calendar["Google Calendar"]
  node_payments["Stripe"]
  node_mail["Gmail"]
end

node_practitioner(("Practitioner"))
node_patient(("Patient"))

node_practitioner -->|"documents visit"| node_consultation
node_patient -.->|"books visit"| node_booking
node_patient -->|"signs in"| node_patientjoin
node_consultation -.->|"reviews form"| node_formwork
node_webapp -->|"checks status"| node_webengine
node_webengine -->|"reads status"| node_supabase
node_webapp -->|"uses client"| node_supabase
node_workercli -->|"starts engine"| node_jobengine
node_jobengine -->|"claims jobs"| node_supabase
node_jobengine -->|"fills fields"| node_formfill
node_jobengine -->|"loads document lines"| node_documents
node_otp -->|"uses server helpers"| node_edgecommon
node_otp -.->|"sends codes"| node_mail
node_otp -->|"sends phone codes"| node_gateway
node_booking -.->|"calendar integration"| node_calendar
node_patientjoin -.->|"requests sign-in"| node_otp
node_paymentfn -.->|"payment integration"| node_payments
node_googlefn -.->|"calendar integration"| node_calendar
node_gateway -->|"forwards events"| node_whatsappfn
node_whatsappfn -.->|"requests delivery"| node_gateway
node_gateway -->|"seals pairing"| node_sealed
node_whatsappfn -->|"uses wording"| node_messages
node_cleanup -->|"uses server helpers"| node_edgecommon
node_paymentfn -->|"uses server helpers"| node_edgecommon
node_googlefn -->|"uses server helpers"| node_edgecommon

click node_webapp "https://github.com/watson-assists/watson/tree/main/apps/web/src/app"
click node_consultation "https://github.com/watson-assists/watson/blob/main/apps/web/src/app/consultation/page.tsx"
click node_booking "https://github.com/watson-assists/watson/blob/main/apps/web/src/app/book/page.tsx"
click node_formwork "https://github.com/watson-assists/watson/blob/main/apps/web/src/app/form/page.tsx"
click node_patientjoin "https://github.com/watson-assists/watson/blob/main/apps/web/src/app/join/page.tsx"
click node_webengine "https://github.com/watson-assists/watson/blob/main/apps/web/src/lib/engine.ts"
click node_dbtypes "https://github.com/watson-assists/watson/blob/main/apps/web/src/lib/database.types.ts"
click node_workercli "https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/__main__.py"
click node_jobengine "https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/engine.py"
click node_audio "https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/audio.py"
click node_transcription "https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/transcribe.py"
click node_merge "https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/merge.py"
click node_formfill "https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/form.py"
click node_documents "https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/documents.py"
click node_schema "https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/schema.py"
click node_supabase "https://github.com/watson-assists/watson/blob/main/apps/web/src/lib/supabase.ts"
click node_edgecommon "https://github.com/watson-assists/watson/blob/main/supabase/functions/_shared/server.ts"
click node_otp "https://github.com/watson-assists/watson/blob/main/supabase/functions/patient-otp/index.ts"
click node_googlefn "https://github.com/watson-assists/watson/blob/main/supabase/functions/google/index.ts"
click node_paymentfn "https://github.com/watson-assists/watson/blob/main/supabase/functions/payment/index.ts"
click node_cleanup "https://github.com/watson-assists/watson/blob/main/supabase/functions/document-cleanup/index.ts"
click node_whatsappfn "https://github.com/watson-assists/watson/blob/main/supabase/functions/whatsapp/index.ts"
click node_messages "https://github.com/watson-assists/watson/blob/main/supabase/functions/whatsapp/messages.ts"
click node_gateway "https://github.com/watson-assists/watson/blob/main/apps/whatsapp-gateway/server.mjs"
click node_sealed "https://github.com/watson-assists/watson/blob/main/apps/whatsapp-gateway/sealed.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_consultation,node_booking,node_formwork,node_patientjoin,node_webengine,node_dbtypes toneBlue
class node_workercli,node_jobengine,node_audio,node_transcription,node_merge,node_formfill,node_documents,node_schema toneAmber
class node_supabase,node_edgecommon,node_otp,node_googlefn,node_paymentfn,node_cleanup toneMint
class node_whatsappfn,node_messages,node_gateway,node_sealed toneRose
class node_calendar,node_payments,node_mail,node_practitioner,node_patient toneIndigo
```

## Components

### Practitioner and Patient Web

- [Watson Web App](https://github.com/watson-assists/watson/tree/main/apps/web/src/app): `apps/web/src/app`
- [Consultation Workspace](https://github.com/watson-assists/watson/blob/main/apps/web/src/app/consultation/page.tsx): `apps/web/src/app/consultation/page.tsx`
- [Booking](https://github.com/watson-assists/watson/blob/main/apps/web/src/app/book/page.tsx): `apps/web/src/app/book/page.tsx`
- [Form Review](https://github.com/watson-assists/watson/blob/main/apps/web/src/app/form/page.tsx): `apps/web/src/app/form/page.tsx`
- [Patient Join](https://github.com/watson-assists/watson/blob/main/apps/web/src/app/join/page.tsx): `apps/web/src/app/join/page.tsx`
- [Engine Status](https://github.com/watson-assists/watson/blob/main/apps/web/src/lib/engine.ts): `apps/web/src/lib/engine.ts`
- [Database Types](https://github.com/watson-assists/watson/blob/main/apps/web/src/lib/database.types.ts): `apps/web/src/lib/database.types.ts`

### Clinical Processing

- [Worker CLI](https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/__main__.py): `apps/clinical-worker/src/clinical_worker/__main__.py`
- [Job Engine](https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/engine.py): `apps/clinical-worker/src/clinical_worker/engine.py`
- [Audio Handling](https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/audio.py): `apps/clinical-worker/src/clinical_worker/audio.py`
- [Transcription](https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/transcribe.py): `apps/clinical-worker/src/clinical_worker/transcribe.py`
- [Transcript Merge](https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/merge.py): `apps/clinical-worker/src/clinical_worker/merge.py`
- [Form Filling](https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/form.py): `apps/clinical-worker/src/clinical_worker/form.py`
- [Document Processing](https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/documents.py): `apps/clinical-worker/src/clinical_worker/documents.py`
- [Output Schema](https://github.com/watson-assists/watson/blob/main/apps/clinical-worker/src/clinical_worker/schema.py): `apps/clinical-worker/src/clinical_worker/schema.py`

### Supabase Platform

- [Supabase Database](https://github.com/watson-assists/watson/blob/main/apps/web/src/lib/supabase.ts): `apps/web/src/lib/supabase.ts`
- [Edge Function Server](https://github.com/watson-assists/watson/blob/main/supabase/functions/_shared/server.ts): `supabase/functions/_shared/server.ts`
- [Patient OTP](https://github.com/watson-assists/watson/blob/main/supabase/functions/patient-otp/index.ts): `supabase/functions/patient-otp/index.ts`
- [Google Calendar Function](https://github.com/watson-assists/watson/blob/main/supabase/functions/google/index.ts): `supabase/functions/google/index.ts`
- [Payment Function](https://github.com/watson-assists/watson/blob/main/supabase/functions/payment/index.ts): `supabase/functions/payment/index.ts`
- [Document Cleanup](https://github.com/watson-assists/watson/blob/main/supabase/functions/document-cleanup/index.ts): `supabase/functions/document-cleanup/index.ts`

### WhatsApp Messaging

- [WhatsApp Function](https://github.com/watson-assists/watson/blob/main/supabase/functions/whatsapp/index.ts): `supabase/functions/whatsapp/index.ts`
- [Message Wording](https://github.com/watson-assists/watson/blob/main/supabase/functions/whatsapp/messages.ts): `supabase/functions/whatsapp/messages.ts`
- [WhatsApp Gateway](https://github.com/watson-assists/watson/blob/main/apps/whatsapp-gateway/server.mjs): `apps/whatsapp-gateway/server.mjs`
- [Pairing Encryption](https://github.com/watson-assists/watson/blob/main/apps/whatsapp-gateway/sealed.mjs): `apps/whatsapp-gateway/sealed.mjs`

### External Integrations

- **Google Calendar**
- **Stripe**
- **Gmail**

### Other components

- **Practitioner**
- **Patient**

## Connections

- Practitioner → Consultation Workspace: documents visit (evidence: `README.md`)
- Patient → Booking: books visit (evidence: `README.md`)
- Patient → Patient Join: signs in (evidence: `README.md`)
- Consultation Workspace → Form Review: reviews form (evidence: `README.md`)
- Watson Web App → Engine Status: checks status (evidence: `apps/web/src/lib/engine.ts`)
- Engine Status → Supabase Database: reads status (evidence: `apps/web/src/lib/engine.ts`)
- Watson Web App → Supabase Database: uses client (evidence: `apps/web/src/lib/supabase.ts`)
- Worker CLI → Job Engine: starts engine (evidence: `apps/clinical-worker/src/clinical_worker/__main__.py`)
- Job Engine → Supabase Database: claims jobs (evidence: `apps/clinical-worker/src/clinical_worker/engine.py`)
- Job Engine → Form Filling: fills fields (evidence: `apps/clinical-worker/src/clinical_worker/engine.py`)
- Job Engine → Document Processing: loads document lines (evidence: `apps/clinical-worker/src/clinical_worker/engine.py`)
- Patient OTP → Edge Function Server: uses server helpers (evidence: `supabase/functions/patient-otp/index.ts`)
- Patient OTP → Gmail: sends codes (evidence: `README.md`)
- Patient OTP → WhatsApp Gateway: sends phone codes (evidence: `supabase/functions/patient-otp/index.ts`)
- Booking → Google Calendar: calendar integration (evidence: `README.md`)
- Patient Join → Patient OTP: requests sign-in (evidence: `README.md`)
- Payment Function → Stripe: payment integration (evidence: `README.md`)
- Google Calendar Function → Google Calendar: calendar integration (evidence: `README.md`)
- WhatsApp Gateway → WhatsApp Function: forwards events (evidence: `apps/whatsapp-gateway/server.mjs`)
- WhatsApp Function → WhatsApp Gateway: requests delivery (evidence: `supabase/functions/whatsapp/index.ts`)
- WhatsApp Gateway → Pairing Encryption: seals pairing (evidence: `apps/whatsapp-gateway/server.mjs`)
- WhatsApp Function → Message Wording: uses wording (evidence: `supabase/functions/whatsapp/messages.ts`)
- Document Cleanup → Edge Function Server: uses server helpers (evidence: `supabase/functions/document-cleanup/index.ts`)
- Payment Function → Edge Function Server: uses server helpers (evidence: `supabase/functions/payment/index.ts`)
- Google Calendar Function → Edge Function Server: uses server helpers (evidence: `supabase/functions/google/index.ts`)