# zeynepersoz/neurooncotrackai architecture

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

- Interactive diagram: https://gitdiagram.com/zeynepersoz/neurooncotrackai
- Repository: https://github.com/zeynepersoz/neurooncotrackai

## Overview

NeuroOncoTrack-AI’s `ai` branch is the AI HTTP microservice, not the full clinical platform. Its documented principal workflow is HTTP request → bridge orchestration → preprocessing, classification, XAI, and RAG report generation. Preprocessing and the RAG internals are supported by sampled source; the bridge’s stage links are documented in the README and partially visible in its excerpt. The README describes further segmentation, radiomics, and FHIR capabilities, but their runtime wiring is not fully established by the available excerpts, so those are not presented as confirmed pipeline stages.

Main entry points: [`ai_service/bridge.py`](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/bridge.py) (Pipeline bridge), [`ai_service/mert/preprocessing/pipeline.py`](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/pipeline.py) (Preprocessing pipeline), [`ai_service/mert/llm/rag_pipeline.py`](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/rag_pipeline.py) (RAG generation), [`ai_service/mert/core/end_to_end.py`](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/core/end_to_end.py) (Report orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Service entry"]
  node_http_service["HTTP service<br/>[serve.py]"]
  node_bridge["Pipeline bridge<br/>[bridge.py]"]
end

subgraph group_prep["Image preparation"]
  node_preprocess["Preprocessing pipeline<br/>[pipeline.py]"]
  node_qc["Input quality checks<br/>[qc.py]"]
  node_skull_strip["Skull stripping<br/>[skull_strip.py]"]
  node_bias_correction["Bias correction<br/>[bias_correction.py]"]
  node_registration["Modality registration<br/>[registration.py]"]
  node_normalization["Resample and normalize<br/>[normalize.py]"]
end

subgraph group_models["Inference and XAI"]
  node_classifier_v3["V3 classifier<br/>[v3_predictor.py]"]
  node_classifier_v2["V2 classifier<br/>[v2_predictor.py]"]
  node_segmentation["Segmentation predictor"]
  node_xai_overlay["XAI overlay<br/>[overlay.py]"]
end

subgraph group_reporting["Clinical reporting"]
  node_report_pipeline["Report orchestrator<br/>[end_to_end.py]"]
  node_embedder["Text embedder<br/>[embedder.py]"]
  node_vector_store[("Guideline search<br/>[vector_store.py]")]
  node_rag["RAG generation<br/>[rag_pipeline.py]"]
  node_validator["Report validation"]
  node_prompt["Report instructions<br/>[system_prompt.py]"]
end

node_backend(("Backend client"))
node_groq["Groq LLM service"]

node_backend -->|"sends request"| node_http_service
node_http_service -->|"calls pipeline"| node_bridge
node_bridge -->|"runs preprocessing"| node_preprocess
node_bridge -->|"classifies"| node_classifier_v3
node_bridge -->|"selects predictor"| node_classifier_v2
node_bridge -->|"builds overlay"| node_xai_overlay
node_bridge -->|"generates report"| node_report_pipeline
node_preprocess -->|"checks inputs"| node_qc
node_preprocess -->|"strips brain"| node_skull_strip
node_preprocess -->|"corrects bias"| node_bias_correction
node_preprocess -->|"registers modalities"| node_registration
node_preprocess -->|"normalizes images"| node_normalization
node_classifier_v3 -->|"reuses preprocessing"| node_classifier_v2
node_report_pipeline -->|"embeds query"| node_embedder
node_report_pipeline -->|"builds and searches"| node_vector_store
node_report_pipeline -->|"requests report"| node_rag
node_rag -->|"retrieves context"| node_vector_store
node_rag -->|"formats prompt"| node_prompt
node_rag -->|"validates output"| node_validator
node_validator -->|"uses report rules"| node_prompt
node_rag -->|"requests completion"| node_groq

click node_http_service "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/serve.py"
click node_bridge "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/bridge.py"
click node_preprocess "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/pipeline.py"
click node_qc "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/qc.py"
click node_skull_strip "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/skull_strip.py"
click node_bias_correction "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/bias_correction.py"
click node_registration "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/registration.py"
click node_normalization "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/normalize.py"
click node_classifier_v3 "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/zeynep/v3_predictor.py"
click node_classifier_v2 "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/zeynep/v2_predictor.py"
click node_segmentation "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/zeynep/segmentation_predictor.py"
click node_xai_overlay "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/xai/overlay.py"
click node_report_pipeline "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/core/end_to_end.py"
click node_embedder "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/embedder.py"
click node_vector_store "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/vector_store.py"
click node_rag "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/rag_pipeline.py"
click node_validator "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/report_validator.py"
click node_prompt "https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/system_prompt.py"

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_http_service,node_bridge,node_backend toneBlue
class node_preprocess,node_qc,node_skull_strip,node_bias_correction,node_registration,node_normalization toneAmber
class node_classifier_v3,node_classifier_v2,node_segmentation,node_xai_overlay toneMint
class node_report_pipeline,node_embedder,node_vector_store,node_rag,node_validator,node_prompt toneRose
class node_groq toneIndigo
```

## Components

### Service entry

- [HTTP service](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/serve.py): `ai_service/serve.py`
- [Pipeline bridge](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/bridge.py): `ai_service/bridge.py`

### Image preparation

- [Preprocessing pipeline](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/pipeline.py): `ai_service/mert/preprocessing/pipeline.py`
- [Input quality checks](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/qc.py): `ai_service/mert/preprocessing/qc.py`
- [Skull stripping](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/skull_strip.py): `ai_service/mert/preprocessing/skull_strip.py`
- [Bias correction](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/bias_correction.py): `ai_service/mert/preprocessing/bias_correction.py`
- [Modality registration](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/registration.py): `ai_service/mert/preprocessing/registration.py`
- [Resample and normalize](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/preprocessing/normalize.py): `ai_service/mert/preprocessing/normalize.py`

### Inference and XAI

- [V3 classifier](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/zeynep/v3_predictor.py): `ai_service/zeynep/v3_predictor.py`
- [V2 classifier](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/zeynep/v2_predictor.py): `ai_service/zeynep/v2_predictor.py`
- [Segmentation predictor](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/zeynep/segmentation_predictor.py): `ai_service/zeynep/segmentation_predictor.py`
- [XAI overlay](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/xai/overlay.py): `ai_service/mert/xai/overlay.py`

### Clinical reporting

- [Report orchestrator](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/core/end_to_end.py): `ai_service/mert/core/end_to_end.py`
- [Text embedder](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/embedder.py): `ai_service/mert/llm/embedder.py`
- [Guideline search](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/vector_store.py): `ai_service/mert/llm/vector_store.py`
- [RAG generation](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/rag_pipeline.py): `ai_service/mert/llm/rag_pipeline.py`
- [Report validation](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/report_validator.py): `ai_service/mert/llm/report_validator.py`
- [Report instructions](https://github.com/zeynepersoz/neurooncotrackai/blob/ai/ai_service/mert/llm/system_prompt.py): `ai_service/mert/llm/system_prompt.py`

### Other components

- **Backend client**
- **Groq LLM service**

## Connections

- Backend client → HTTP service: sends request (evidence: `README.md`)
- HTTP service → Pipeline bridge: calls pipeline (evidence: `ai_service/serve.py`)
- Pipeline bridge → Preprocessing pipeline: runs preprocessing (evidence: `README.md`)
- Pipeline bridge → V3 classifier: classifies (evidence: `ai_service/bridge.py`)
- Pipeline bridge → V2 classifier: selects predictor (evidence: `ai_service/bridge.py`)
- Pipeline bridge → XAI overlay: builds overlay (evidence: `ai_service/bridge.py`)
- Pipeline bridge → Report orchestrator: generates report (evidence: `README.md`)
- Preprocessing pipeline → Input quality checks: checks inputs (evidence: `ai_service/mert/preprocessing/pipeline.py`)
- Preprocessing pipeline → Skull stripping: strips brain (evidence: `ai_service/mert/preprocessing/pipeline.py`)
- Preprocessing pipeline → Bias correction: corrects bias (evidence: `ai_service/mert/preprocessing/pipeline.py`)
- Preprocessing pipeline → Modality registration: registers modalities (evidence: `ai_service/mert/preprocessing/pipeline.py`)
- Preprocessing pipeline → Resample and normalize: normalizes images (evidence: `ai_service/mert/preprocessing/pipeline.py`)
- V3 classifier → V2 classifier: reuses preprocessing (evidence: `ai_service/zeynep/v3_predictor.py`)
- Report orchestrator → Text embedder: embeds query (evidence: `ai_service/mert/core/end_to_end.py`)
- Report orchestrator → Guideline search: builds and searches (evidence: `ai_service/mert/core/end_to_end.py`)
- Report orchestrator → RAG generation: requests report (evidence: `ai_service/mert/core/end_to_end.py`)
- RAG generation → Guideline search: retrieves context (evidence: `ai_service/mert/llm/rag_pipeline.py`)
- RAG generation → Report instructions: formats prompt (evidence: `ai_service/mert/llm/rag_pipeline.py`)
- RAG generation → Report validation: validates output (evidence: `ai_service/mert/llm/rag_pipeline.py`)
- Report validation → Report instructions: uses report rules (evidence: `ai_service/mert/llm/report_validator.py`)
- RAG generation → Groq LLM service: requests completion (evidence: `ai_service/mert/llm/rag_pipeline.py`)
