# marksman8/parkinson-ai architecture

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

- Interactive diagram: https://gitdiagram.com/marksman8/parkinson-ai
- Repository: https://github.com/marksman8/parkinson-ai

## Overview

NeuroSync PD is a Parkinson’s clinical AI system with a unified dashboard and separate biomarker, multimodal clinical, retrieval-augmented, and diagnostic services. The user-facing flow starts at the dashboard, which launches the service backends; clinical requests are routed to task handlers, while biomarker discovery orchestrates relevance checks, pathway/network analysis, and stored results. The graph also preserves document ingestion and evaluation as distinct capabilities. Relationships are limited to launcher documentation and source-index references or calls visible in excerpts; unsampled wiring is omitted.

Main entry points: [`module0_biomarker/core/engine.py`](https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/core/engine.py) (Discovery orchestrator), [`pd_multimodal/api/main.py`](https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/api/main.py) (Clinical API), [`launcher.py`](https://github.com/marksman8/parkinson-ai/blob/main/launcher.py) (Dashboard launcher), [`pd_rag/multimodal_engine_rag.py`](https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/multimodal_engine_rag.py) (RAG clinical engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_launcher["Dashboard launcher<br/>[launcher.py]"]
end

subgraph group_clinical["Clinical AI"]
  node_multimodal_api["Clinical API<br/>[main.py]"]
  node_engine["Multimodal engine"]
  node_config["Model configuration<br/>[config.py]"]
  node_router["Intent router<br/>[router.py]"]
  node_ode["Neuron simulation<br/>[ode_simulator.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_rag_engine["RAG clinical engine"]
  node_trigger["RAG trigger<br/>[trigger.py]"]
  node_retriever["Knowledge retriever<br/>[retriever.py]"]
  node_ingestor["Knowledge ingestion<br/>[ingestor.py]"]
  node_vector_db[("Vector database")]
end

subgraph group_biomarkers["Biomarker discovery"]
  node_biomarker_api["Biomarker API<br/>[main.py]"]
  node_biomarker_engine["Discovery orchestrator<br/>[engine.py]"]
  node_relevance["PD relevance check<br/>[relevance.py]"]
  node_network["Pathway and PPI<br/>[kegg_string.py]"]
  node_gene_info["Gene annotation<br/>[gene_info.py]"]
  node_memory[("Patient memory<br/>[memory_store.py]")]
  node_bridge["Module 0 bridge<br/>[module0_bridge.py]"]
  node_pdf["PDF reporting<br/>[pdf_generator.py]"]
end

subgraph group_operations["Diagnostics and evaluation"]
  node_debugger_api["Debugger API<br/>[main.py]"]
  node_debugger["System diagnostics<br/>[debugger.py]"]
  node_rag_eval["RAG evaluation<br/>[metrics.py]"]
  node_clinical_eval["Clinical evaluation<br/>[train_eval.py]"]
end

node_user(("Clinician"))

node_user -->|"uses dashboard"| node_launcher
node_launcher -->|"spawns service"| node_multimodal_api
node_launcher -->|"spawns service"| node_biomarker_api
node_launcher -->|"spawns service"| node_debugger_api
node_multimodal_api -->|"calls tasks"| node_engine
node_multimodal_api -->|"loads settings"| node_config
node_multimodal_api -->|"dispatches requests"| node_router
node_multimodal_api -->|"runs simulation"| node_ode
node_router -->|"dispatches tasks"| node_engine
node_router -->|"runs simulation"| node_ode
node_rag_engine -->|"classifies queries"| node_trigger
node_rag_engine -->|"retrieves context"| node_retriever
node_rag_engine -->|"ingests documents"| node_ingestor
node_retriever -->|"queries collections"| node_vector_db
node_ingestor -->|"writes embeddings"| node_vector_db
node_biomarker_api -->|"runs discovery"| node_biomarker_engine
node_biomarker_api -->|"reads context"| node_memory
node_biomarker_engine -->|"checks relevance"| node_relevance
node_biomarker_engine -->|"builds PPI"| node_network
node_biomarker_engine -->|"annotates genes"| node_gene_info
node_biomarker_engine -->|"saves results"| node_memory
node_biomarker_engine -->|"generates report"| node_pdf
node_debugger_api -->|"runs checks"| node_debugger

click node_launcher "https://github.com/marksman8/parkinson-ai/blob/main/launcher.py"
click node_multimodal_api "https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/api/main.py"
click node_engine "https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/core/multimodal_engine.py"
click node_config "https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/config.py"
click node_router "https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/modules/module7_router/router.py"
click node_ode "https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/modules/module6_ode/ode_simulator.py"
click node_rag_engine "https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/multimodal_engine_rag.py"
click node_trigger "https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/core/trigger.py"
click node_retriever "https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/retrieval/retriever.py"
click node_ingestor "https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/ingest/ingestor.py"
click node_biomarker_api "https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/api/main.py"
click node_biomarker_engine "https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/core/engine.py"
click node_relevance "https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/rag/relevance.py"
click node_network "https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/network/kegg_string.py"
click node_gene_info "https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/core/gene_info.py"
click node_memory "https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/core/memory_store.py"
click node_bridge "https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/integration/module0_bridge.py"
click node_pdf "https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/report/pdf_generator.py"
click node_debugger_api "https://github.com/marksman8/parkinson-ai/blob/main/pd_debugger/api/main.py"
click node_debugger "https://github.com/marksman8/parkinson-ai/blob/main/pd_debugger/core/debugger.py"
click node_rag_eval "https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/eval/metrics.py"
click node_clinical_eval "https://github.com/marksman8/parkinson-ai/blob/main/pd_clinical/eval/train_eval.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_launcher toneBlue
class node_multimodal_api,node_engine,node_config,node_router,node_ode toneAmber
class node_rag_engine,node_trigger,node_retriever,node_ingestor,node_vector_db toneMint
class node_biomarker_api,node_biomarker_engine,node_relevance,node_network,node_gene_info,node_memory,node_bridge,node_pdf toneRose
class node_debugger_api,node_debugger,node_rag_eval,node_clinical_eval,node_user toneIndigo
```

## Components

### User entry

- [Dashboard launcher](https://github.com/marksman8/parkinson-ai/blob/main/launcher.py): `launcher.py`

### Clinical AI

- [Clinical API](https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/api/main.py): `pd_multimodal/api/main.py`
- [Multimodal engine](https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/core/multimodal_engine.py): `pd_multimodal/core/multimodal_engine.py`
- [Model configuration](https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/config.py): `pd_multimodal/config.py`
- [Intent router](https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/modules/module7_router/router.py): `pd_multimodal/modules/module7_router/router.py`
- [Neuron simulation](https://github.com/marksman8/parkinson-ai/blob/main/pd_multimodal/modules/module6_ode/ode_simulator.py): `pd_multimodal/modules/module6_ode/ode_simulator.py`

### Knowledge retrieval

- [RAG clinical engine](https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/multimodal_engine_rag.py): `pd_rag/multimodal_engine_rag.py`
- [RAG trigger](https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/core/trigger.py): `pd_rag/core/trigger.py`
- [Knowledge retriever](https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/retrieval/retriever.py): `pd_rag/retrieval/retriever.py`
- [Knowledge ingestion](https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/ingest/ingestor.py): `pd_rag/ingest/ingestor.py`
- **Vector database**

### Biomarker discovery

- [Biomarker API](https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/api/main.py): `module0_biomarker/api/main.py`
- [Discovery orchestrator](https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/core/engine.py): `module0_biomarker/core/engine.py`
- [PD relevance check](https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/rag/relevance.py): `module0_biomarker/rag/relevance.py`
- [Pathway and PPI](https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/network/kegg_string.py): `module0_biomarker/network/kegg_string.py`
- [Gene annotation](https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/core/gene_info.py): `module0_biomarker/core/gene_info.py`
- [Patient memory](https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/core/memory_store.py): `module0_biomarker/core/memory_store.py`
- [Module 0 bridge](https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/integration/module0_bridge.py): `module0_biomarker/integration/module0_bridge.py`
- [PDF reporting](https://github.com/marksman8/parkinson-ai/blob/main/module0_biomarker/report/pdf_generator.py): `module0_biomarker/report/pdf_generator.py`

### Diagnostics and evaluation

- [Debugger API](https://github.com/marksman8/parkinson-ai/blob/main/pd_debugger/api/main.py): `pd_debugger/api/main.py`
- [System diagnostics](https://github.com/marksman8/parkinson-ai/blob/main/pd_debugger/core/debugger.py): `pd_debugger/core/debugger.py`
- [RAG evaluation](https://github.com/marksman8/parkinson-ai/blob/main/pd_rag/eval/metrics.py): `pd_rag/eval/metrics.py`
- [Clinical evaluation](https://github.com/marksman8/parkinson-ai/blob/main/pd_clinical/eval/train_eval.py): `pd_clinical/eval/train_eval.py`

### Other components

- **Clinician**

## Connections

- Clinician → Dashboard launcher: uses dashboard (evidence: `launcher.py`)
- Dashboard launcher → Clinical API: spawns service (evidence: `launcher.py`)
- Dashboard launcher → Biomarker API: spawns service (evidence: `launcher.py`)
- Dashboard launcher → Debugger API: spawns service (evidence: `launcher.py`)
- Clinical API → Multimodal engine: calls tasks (evidence: `pd_multimodal/api/main.py`)
- Clinical API → Model configuration: loads settings (evidence: `pd_multimodal/api/main.py`)
- Clinical API → Intent router: dispatches requests (evidence: `pd_multimodal/api/main.py`)
- Clinical API → Neuron simulation: runs simulation (evidence: `pd_multimodal/api/main.py`)
- Intent router → Multimodal engine: dispatches tasks (evidence: `pd_multimodal/modules/module7_router/router.py`)
- Intent router → Neuron simulation: runs simulation (evidence: `pd_multimodal/modules/module7_router/router.py`)
- RAG clinical engine → RAG trigger: classifies queries (evidence: `pd_rag/multimodal_engine_rag.py`)
- RAG clinical engine → Knowledge retriever: retrieves context (evidence: `pd_rag/multimodal_engine_rag.py`)
- RAG clinical engine → Knowledge ingestion: ingests documents (evidence: `pd_rag/multimodal_engine_rag.py`)
- Knowledge retriever → Vector database: queries collections (evidence: `pd_rag/retrieval/retriever.py`)
- Knowledge ingestion → Vector database: writes embeddings (evidence: `pd_rag/ingest/ingestor.py`)
- Biomarker API → Discovery orchestrator: runs discovery (evidence: `module0_biomarker/api/main.py`)
- Biomarker API → Patient memory: reads context (evidence: `module0_biomarker/api/main.py`)
- Discovery orchestrator → PD relevance check: checks relevance (evidence: `module0_biomarker/core/engine.py`)
- Discovery orchestrator → Pathway and PPI: builds PPI (evidence: `module0_biomarker/core/engine.py`)
- Discovery orchestrator → Gene annotation: annotates genes (evidence: `module0_biomarker/core/engine.py`)
- Discovery orchestrator → Patient memory: saves results (evidence: `module0_biomarker/core/engine.py`)
- Discovery orchestrator → PDF reporting: generates report (evidence: `module0_biomarker/core/engine.py`)
- Debugger API → System diagnostics: runs checks (evidence: `pd_debugger/api/main.py`)
