RheumAI architecture

System map

flowchart TB
  UI["Preact web app"] --> API["Elysia API"]
  EXT["External client"] --> API
  STUDY["BiobadamexAI study harness"] --> SR["Stateless study route"]

  API --> ACCESS["Auth · rate limits · optional x402"]
  ACCESS --> SETUP["Conversation and state"]
  SETUP --> PLAN["PLANNING"]
  PLAN --> TOOLS["Clinical tools and sources"]
  TOOLS --> RET["DAG / RAG / graph"]
  RET --> REPLY["REPLY or HYPOTHESIS"]
  REPLY --> ORVS["ORVS + PMID control"]
  ORVS --> ETH["Ethical review"]
  ETH --> UI

  SR --> PLAN2["PLANNING with tool cap"]
  PLAN2 --> TOOLS2["Allowed tools"]
  TOOLS2 --> REPLY2["REPLY"]
  REPLY2 --> STUDY

  SETUP --> DB[("Supabase")]
  TOOLS --> OBJ[("S3-compatible storage")]
  TOOLS --> LIT["PubMed · Semantic Scholar · OpenScholar · local knowledge"]

Components

Web client

The Preact client manages sessions, authentication, uploads, chat requests, citations, and payment states. The backend serves the bundle and uses a single-page-app fallback.

Elysia API

src/index.ts mounts authentication, configuration, chat, deep research, community, search, cryptography, and study routes. It also serves the client and health endpoints.

State and persistence

Normal chat creates users, conversations, messages, and request state in Supabase. Files can be written to S3-compatible storage, while parsed content enters request state. /api/chat is therefore not stateless.

The study route uses nil UUIDs and omits message and state identifiers. This gates off writes by design. It accepts de-identified text, can pin one provider/model, and returns attribution, tool use, latency, and token usage.

Planner and tools

The tool registry discovers folders under src/tools/ and loads enabled index.ts modules. TOOL_<NAME>_ENABLED variables can override registration. The planner chooses sources and the primary action.

Relevant families include:

Evidence: PubMed, Semantic Scholar, OpenScholar, local knowledge, and knowledge graph.
Clinical: clinical reasoning, lab interpretation, insurance summary, and protocols.
Synthesis: REPLY, HYPOTHESIS, reflection, and ethical review.
Infrastructure: files, data analysis, storage, and medical x402 services.

A folder’s presence does not prove that it loads. Registration logs failures and continues with available tools.

Retrieval and ranking

The pipeline can combine embeddings, local graph retrieval, and semantic search. DAG-RETRIEVAL reranks documents for the question. Some modes fall back to a direct model response when useful evidence is unavailable.

Models

The LLM library exposes a common interface across providers. resilientChatCompletion implements fallbacks. A study context can pin all observable model calls to one provider/model and disable cross-model fallback.

Two flows that must not be confused

Aspect	Normal chat	Study route
Endpoint	`/api/chat`	`/v1/study/rheumaai-reply`
Persistence	Yes	No, by design
Files	Yes	Note text only
Session	Persistent conversation	Isolated request
Auth	Session, client, or x402 depending on config	Dedicated bearer; closed when key is unset
Tools	Planner-selected	Allowlist and cost ceiling
Post-response ORVS	Yes in normal flow; explicit comparison modes available	No explicit final ORVS call in this route
Output	Conversational response	Response, attribution, and turn telemetry

External dependencies

Supabase for conversations, messages, state, and search.
S3-compatible storage for files when configured.
Configurable LLM providers.
PubMed, Semantic Scholar, OpenScholar, and local corpora for evidence.
Optional medical x402 services.
Railway and rheumai.xyz according to repository configuration.