# lmrgroupai/vmpvt3 architecture

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

- Interactive diagram: https://gitdiagram.com/lmrgroupai/vmpvt3
- Repository: https://github.com/lmrgroupai/vmpvt3

## Overview

1. **What this repo is**
   - This is a Dockerized clinical/health decision-support system with a Python backend and a React/Vite frontend.
   - The backend appears modular, with multiple “engines” for reasoning, retrieval, rules, monitoring, and domain-specific workflows.

2. **User-facing presentation layer**
   - The interactive UI lives under `frontend/src` with the main React entrypoint at `frontend/src/main.jsx` and app shell in `frontend/src/App.jsx`.
   - The built frontend is also checked in under `static/`, which suggests the Python app can serve precompiled assets directly.
   - There are duplicate `frontend/frontend/*` files, which look like a nested copy from packaging/build history rather than a separate product surface.

3. **Backend entrypoints and composition**
   - The backend has several possible launch paths: `start.py`, `api_server.py`, `app_full.py`, `app_minimal.py`, and multiple `enhanced_api_v3*` variants.
   - This usually means the system supports different deployment profiles: a minimal API, a fuller orchestration mode, and patched/experimental variants.
   - For an architecture diagram, treat these as alternative compositions over the same underlying modules, not separate products.

4. **Core orchestration / clinical reasoning layer**
   - Files like `comprehensive_clinical_engine.py`, `preventive_engine.py`, `drug_discovery_agent.py`, and `rag_engine.py` indicate the main business logic is split by use case.
   - `comprehensive_clinical_engine.py` is likely the top-level orchestrator that combines multiple reasoning modes into one clinical response.
   - `preventive_engine.py` and `drug_discovery_agent.py` appear to be specialized sub-engines for narrower workflows.

5. **Knowledge and retrieval subsystem**
   - `rag_engine.py`, `canonical_registry.py`, `golden_dataset_synonyms.py`, and `amplify_dataset.py` suggest a knowledge-driven system with retrieval and normalization.
   - The retrieval path likely maps user input to canonical clinical terms, synonyms, and curated datasets before generating output.
   - This is the likely boundary between raw user language and structured medical reasoning.

6. **Rules, experts, and ensemble logic**
   - `classical_rules.py`, `moe_experts.py`, `pillar_28_module.py`, `pillar_29_module.py`, `pillar_30_module.py`, `ansha_kalpana.py`, and `avarana_ty_module.py` suggest multiple reasoning components are combined, probably via a mixture-of-experts or rule stack.
   - The architecture likely uses deterministic rules plus expert modules to complement retrieval-based generation.
   - A diagram should show these as internal decision layers feeding the final clinical response, not as independent services unless deployed separately.

7. **Model/runtime integration**
   - `rlm_hf.py` implies Hugging Face model integration or model-loading utilities.
   - `enhanced_api_v3_kg_patched.py` hints at a knowledge-graph-aware path, so some variants may incorporate structured graph reasoning in addition to text retrieval.
   - There is no obvious separate database directory, so much of the “knowledge” likely lives in code, serialized datasets, or embedded resources.

8. **Output and response shaping**
   - `output_schema.py` likely defines the contract for API responses and structured clinical outputs.
   - This is an important architectural boundary: internal reasoning can be complex, but external consumers probably receive a normalized schema from this module.
   - If you’re drawing the system, place this right before the API layer returns data to the UI.

9. **Quality control and monitoring**
   - `drift_monitor.py` indicates the system tracks distribution or performance drift, which is important for ML/LLM-backed clinical tools.
   - This suggests a feedback/observability loop separate from the main inference path.
   - `lazy_patch.py` may be a runtime patching or compatibility helper used to stabilize behavior across variants.

10. **Deployment and serving**
   - The root `Dockerfile` and the Hugging Face Spaces metadata in `README.md` show the project is meant to run in a containerized environment.
   - The `static/` bundle and Python entrypoints imply the container likely serves both the API and the compiled UI from one runtime.
   - The presence of both `requirements.txt` and `frontend/package.json` means the repo has two build/runtime stacks: Python for backend and Node/Vite for frontend.

11. **Likely request flow**
   - User input enters the React UI or directly hits the API server.
   - The backend normalizes terminology, consults canonical/synonym datasets, routes the request through rules/RAG/expert modules, then formats the result using the output schema.
   - The response is returned to the frontend, while monitoring logic can observe outputs for drift or quality signals.

12. **Useful architecture boundaries for a diagram**
   - **Presentation boundary:** React app and compiled static assets.
   - **API boundary:** one of the Python server entrypoints.
   - **Reasoning boundary:** clinical engine, preventive engine, drug-discovery agent, rules, and expert modules.
   - **Knowledge boundary:** canonical registry, synonym/dataset modules, RAG, and possible knowledge-graph path.
   - **Ops boundary:** Docker containerization, Hugging Face deployment, and drift monitoring.

Main entry points: [`comprehensive_clinical_engine.py`](https://github.com/lmrgroupai/vmpvt3/blob/main/comprehensive_clinical_engine.py) (Clinical Core), [`api_server.py`](https://github.com/lmrgroupai/vmpvt3/blob/main/api_server.py) (API Entrypoints), [`rag_engine.py`](https://github.com/lmrgroupai/vmpvt3/blob/main/rag_engine.py) (RAG), [`moe_experts.py`](https://github.com/lmrgroupai/vmpvt3/blob/main/moe_experts.py) (Experts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_frontend_app["UI Shell<br/>React app<br/>[App.jsx]"]
  node_frontend_main["Frontend Entry<br/>React entrypoint<br/>[main.jsx]"]
  node_static_bundle["Static Bundle<br/>built assets<br/>[index.html]"]
end

subgraph group_api["API Layer"]
  node_server_entrypoints["API Entrypoints<br/>Python servers<br/>[api_server.py]"]
  node_output_schema["Response Schema<br/>contract<br/>[output_schema.py]"]
end

subgraph group_reasoning["Clinical Reasoning"]
  node_clinical_engine{{"Clinical Core<br/>orchestrator"}}
  node_preventive_engine["Preventive Flow<br/>specialist engine"]
  node_drug_discovery_agent["Drug Agent<br/>specialist engine"]
  node_rules_layer["Rules<br/>[classical_rules.py]"]
  node_expert_ensemble["Experts<br/>[moe_experts.py]"]
  node_pillar_modules["Pillar Modules<br/>domain modules"]
  node_specialist_modules["Specialists<br/>domain modules<br/>[ansha_kalpana.py]"]
end

subgraph group_knowledge["Knowledge Layer"]
  node_rag_engine{{"RAG<br/>retrieval engine<br/>[rag_engine.py]"}}
  node_canonical_registry["Canonical Terms<br/>registry"]
  node_synonym_datasets["Synonyms<br/>curated datasets"]
  node_model_runtime["HF Runtime<br/>model integration<br/>[rlm_hf.py]"]
  node_kg_variant["KG Variant<br/>enhanced API variant"]
end

subgraph group_ops["Operations"]
  node_drift_monitor["Drift Monitor<br/>observability<br/>[drift_monitor.py]"]
  node_runtime_patch["Runtime Patch<br/>compatibility helper<br/>[lazy_patch.py]"]
  node_container["Docker<br/>containerization"]
end

node_frontend_main -->|"boots"| node_frontend_app
node_frontend_app -->|"calls API"| node_server_entrypoints
node_static_bundle -.->|"serves UI"| node_frontend_app
node_server_entrypoints -->|"orchestrates"| node_clinical_engine
node_server_entrypoints -.->|"alt composition"| node_kg_variant
node_clinical_engine -->|"retrieves"| node_rag_engine
node_clinical_engine -->|"applies"| node_rules_layer
node_clinical_engine -->|"routes"| node_expert_ensemble
node_clinical_engine -->|"specializes"| node_preventive_engine
node_clinical_engine -->|"specializes"| node_drug_discovery_agent
node_expert_ensemble -->|"includes"| node_pillar_modules
node_expert_ensemble -->|"includes"| node_specialist_modules
node_rag_engine -->|"normalizes"| node_canonical_registry
node_rag_engine -->|"expands"| node_synonym_datasets
node_rag_engine -->|"runs on"| node_model_runtime
node_clinical_engine -->|"formats"| node_output_schema
node_server_entrypoints -->|"returns"| node_output_schema
node_clinical_engine -.->|"observes"| node_drift_monitor
node_server_entrypoints -.->|"stabilizes"| node_runtime_patch
node_container -->|"packages"| node_server_entrypoints
node_container -->|"ships"| node_static_bundle

click node_frontend_app "https://github.com/lmrgroupai/vmpvt3/blob/main/frontend/src/App.jsx"
click node_frontend_main "https://github.com/lmrgroupai/vmpvt3/blob/main/frontend/src/main.jsx"
click node_static_bundle "https://github.com/lmrgroupai/vmpvt3/blob/main/static/index.html"
click node_server_entrypoints "https://github.com/lmrgroupai/vmpvt3/blob/main/api_server.py"
click node_output_schema "https://github.com/lmrgroupai/vmpvt3/blob/main/output_schema.py"
click node_clinical_engine "https://github.com/lmrgroupai/vmpvt3/blob/main/comprehensive_clinical_engine.py"
click node_preventive_engine "https://github.com/lmrgroupai/vmpvt3/blob/main/preventive_engine.py"
click node_drug_discovery_agent "https://github.com/lmrgroupai/vmpvt3/blob/main/drug_discovery_agent.py"
click node_rules_layer "https://github.com/lmrgroupai/vmpvt3/blob/main/classical_rules.py"
click node_expert_ensemble "https://github.com/lmrgroupai/vmpvt3/blob/main/moe_experts.py"
click node_pillar_modules "https://github.com/lmrgroupai/vmpvt3/blob/main/pillar_28_module.py"
click node_specialist_modules "https://github.com/lmrgroupai/vmpvt3/blob/main/ansha_kalpana.py"
click node_rag_engine "https://github.com/lmrgroupai/vmpvt3/blob/main/rag_engine.py"
click node_canonical_registry "https://github.com/lmrgroupai/vmpvt3/blob/main/canonical_registry.py"
click node_synonym_datasets "https://github.com/lmrgroupai/vmpvt3/blob/main/golden_dataset_synonyms.py"
click node_model_runtime "https://github.com/lmrgroupai/vmpvt3/blob/main/rlm_hf.py"
click node_kg_variant "https://github.com/lmrgroupai/vmpvt3/blob/main/enhanced_api_v3_kg_patched.py"
click node_drift_monitor "https://github.com/lmrgroupai/vmpvt3/blob/main/drift_monitor.py"
click node_runtime_patch "https://github.com/lmrgroupai/vmpvt3/blob/main/lazy_patch.py"
click node_container "https://github.com/lmrgroupai/vmpvt3/tree/main/Dockerfile"

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_frontend_app,node_frontend_main,node_static_bundle toneBlue
class node_server_entrypoints,node_output_schema toneAmber
class node_clinical_engine,node_preventive_engine,node_drug_discovery_agent,node_rules_layer,node_expert_ensemble,node_pillar_modules,node_specialist_modules toneMint
class node_rag_engine,node_canonical_registry,node_synonym_datasets,node_model_runtime,node_kg_variant toneRose
class node_drift_monitor,node_runtime_patch,node_container toneIndigo
```

## Components

### Presentation

User-facing React app and built static assets

- [UI Shell](https://github.com/lmrgroupai/vmpvt3/blob/main/frontend/src/App.jsx): React app · Main interactive frontend shell · `frontend/src/App.jsx`
- [Frontend Entry](https://github.com/lmrgroupai/vmpvt3/blob/main/frontend/src/main.jsx): React entrypoint · Frontend bootstrapping entry · `frontend/src/main.jsx`
- [Static Bundle](https://github.com/lmrgroupai/vmpvt3/blob/main/static/index.html): built assets · Checked-in compiled frontend assets · `static/index.html`

### API Layer

Python server entrypoints and response shaping

- [API Entrypoints](https://github.com/lmrgroupai/vmpvt3/blob/main/api_server.py): Python servers · Alternative backend launch paths and deployment profiles · `api_server.py`
- [Response Schema](https://github.com/lmrgroupai/vmpvt3/blob/main/output_schema.py): contract · Structured clinical output contract · `output_schema.py`

### Clinical Reasoning

Orchestration, rules, experts, and specialty engines

- [Clinical Core](https://github.com/lmrgroupai/vmpvt3/blob/main/comprehensive_clinical_engine.py): orchestrator · Top-level clinical reasoning coordinator · `comprehensive_clinical_engine.py`
- [Preventive Flow](https://github.com/lmrgroupai/vmpvt3/blob/main/preventive_engine.py): specialist engine · Preventive or screening-oriented reasoning path · `preventive_engine.py`
- [Drug Agent](https://github.com/lmrgroupai/vmpvt3/blob/main/drug_discovery_agent.py): specialist engine · Drug-oriented workflow and reasoning · `drug_discovery_agent.py`
- [Rules](https://github.com/lmrgroupai/vmpvt3/blob/main/classical_rules.py): deterministic rules · Classical rule-based decision layer · `classical_rules.py`
- [Experts](https://github.com/lmrgroupai/vmpvt3/blob/main/moe_experts.py): mixture of experts · Expert routing and ensemble decision layer · `moe_experts.py`
- [Pillar Modules](https://github.com/lmrgroupai/vmpvt3/blob/main/pillar_28_module.py): domain modules · Representative pillar-style specialist modules · `pillar_28_module.py`
- [Specialists](https://github.com/lmrgroupai/vmpvt3/blob/main/ansha_kalpana.py): domain modules · Additional named specialist reasoning modules · `ansha_kalpana.py`

### Knowledge Layer

Retrieval, canonicalization, datasets, and model runtime

- [RAG](https://github.com/lmrgroupai/vmpvt3/blob/main/rag_engine.py): retrieval engine · Retrieval-augmented reasoning and grounding · `rag_engine.py`
- [Canonical Terms](https://github.com/lmrgroupai/vmpvt3/blob/main/canonical_registry.py): registry · Terminology normalization and canonical mapping · `canonical_registry.py`
- [Synonyms](https://github.com/lmrgroupai/vmpvt3/blob/main/golden_dataset_synonyms.py): curated datasets · Synonym and dataset normalization resources · `golden_dataset_synonyms.py`
- [HF Runtime](https://github.com/lmrgroupai/vmpvt3/blob/main/rlm_hf.py): model integration · Hugging Face model loading and runtime utilities · `rlm_hf.py`
- [KG Variant](https://github.com/lmrgroupai/vmpvt3/blob/main/enhanced_api_v3_kg_patched.py): enhanced API variant · Knowledge-graph-aware API composition variant · `enhanced_api_v3_kg_patched.py`

### Operations

Containerization, monitoring, and runtime patching

- [Drift Monitor](https://github.com/lmrgroupai/vmpvt3/blob/main/drift_monitor.py): observability · Quality and distribution drift tracking · `drift_monitor.py`
- [Runtime Patch](https://github.com/lmrgroupai/vmpvt3/blob/main/lazy_patch.py): compatibility helper · Compatibility or stabilization patch layer · `lazy_patch.py`
- [Docker](https://github.com/lmrgroupai/vmpvt3/tree/main/Dockerfile): containerization · Container build and serving environment · `Dockerfile`

## Connections

- Frontend Entry → UI Shell: boots · Frontend entry mounts the app shell
- UI Shell → API Entrypoints: calls API · UI sends user requests to backend endpoints
- Static Bundle → UI Shell: serves UI · Prebuilt assets provide the same UI surface
- API Entrypoints → Clinical Core: orchestrates · Server routes requests into the clinical core
- API Entrypoints → KG Variant: alt composition · Variant backend composition path
- Clinical Core → RAG: retrieves · Core reasoning grounds responses through retrieval
- Clinical Core → Rules: applies · Deterministic rules inform final decisions
- Clinical Core → Experts: routes · Expert ensemble contributes specialized judgments
- Clinical Core → Preventive Flow: specializes · Preventive workflow is invoked when relevant
- Clinical Core → Drug Agent: specializes · Drug workflow is invoked when relevant
- Experts → Pillar Modules: includes · Representative pillar modules participate in the ensemble
- Experts → Specialists: includes · Additional specialist modules contribute
- RAG → Canonical Terms: normalizes · Retrieval maps inputs to canonical clinical terms
- RAG → Synonyms: expands · Synonyms and curated datasets broaden matching
- RAG → HF Runtime: runs on · Model runtime supports retrieval and generation
- Clinical Core → Response Schema: formats · Clinical output is shaped into the response contract
- API Entrypoints → Response Schema: returns · API responses are emitted through the schema boundary
- Clinical Core → Drift Monitor: observes · Outputs and behavior are monitored for drift
- API Entrypoints → Runtime Patch: stabilizes · Patch layer can adjust runtime behavior
- Docker → API Entrypoints: packages · Container bundles backend serving entrypoints
- Docker → Static Bundle: ships · Container can serve checked-in frontend assets
