# ohdsi/whiterabbit architecture

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

- Interactive diagram: https://gitdiagram.com/ohdsi/whiterabbit
- Repository: https://github.com/ohdsi/whiterabbit

## Overview

White Rabbit scans database tables or CSV/SAS files, summarizes structure and value frequencies, and produces a scan report for ETL planning. Rabbit in a Hat loads that report, lets users map its source tables and fields to an OMOP CDM target, and generates ETL documentation and related outputs. The graph reflects README capabilities and the supplied source excerpts; unsampled UI-to-engine wiring and several scan implementations are represented only where documented, not as detailed call chains.

Main entry points: [`rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/dataModel/ETL.java`](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/dataModel/ETL.java) (ETL model), [`whiterabbit/src/main/java/org/ohdsi/whiterabbit/scan/SourceDataScan.java`](https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/scan/SourceDataScan.java) (Source scan), [`rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/RabbitInAHatMain.java`](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/RabbitInAHatMain.java) (Rabbit in a Hat), [`whiterabbit/src/main/java/org/ohdsi/whiterabbit/gui/LocationsPanel.java`](https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/gui/LocationsPanel.java) (Source setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan_setup["Scan setup"]
  node_locations_ui["Source setup"]
  node_white_rabbit["White Rabbit"]
end

subgraph group_scan_engine["Scan engine"]
  node_source_scan["Source scan"]
  node_db_config["DB settings"]
  node_db_handlers["DB handlers"]
  node_db_query["Query access<br/>[QueryResult.java]"]
  node_source_files["CSV/SAS input"]
end

subgraph group_etl_design["ETL design"]
  node_riah["Rabbit in a Hat"]
  node_source_model["Scanned model<br/>[Database.java]"]
  node_etl_model["ETL model<br/>[ETL.java]"]
  node_mapping_ui["Mapping editor<br/>[MappingPanel.java]"]
  node_target_model["OMOP target<br/>[Database.java]"]
  node_sql_generator["SQL generator<br/>[SQLGenerator.java]"]
end

subgraph group_etl_outputs["ETL outputs"]
  node_word_output["ETL specification"]
  node_markup_output["Markup document"]
  node_summary_output["ETL summary"]
  node_test_output["ETL test framework"]
end

node_user(("User"))
node_source_database[("Source database")]
node_scan_report["Scan report"]

node_user -->|"starts scan"| node_white_rabbit
node_user -->|"configures source"| node_locations_ui
node_locations_ui -->|"sets options"| node_db_config
node_white_rabbit -->|"runs scan"| node_source_scan
node_source_scan -->|"uses settings"| node_db_config
node_source_scan -->|"scans database"| node_db_handlers
node_db_handlers -->|"executes queries"| node_db_query
node_db_query -->|"reads rows"| node_source_database
node_source_scan -->|"scans files"| node_source_files
node_source_files -->|"writes report"| node_scan_report
node_source_scan -->|"writes report"| node_scan_report
node_user -->|"designs ETL"| node_riah
node_riah -->|"loads scan report"| node_source_model
node_scan_report -->|"provides scan data"| node_source_model
node_riah -->|"edits design"| node_etl_model
node_riah -->|"selects CDM"| node_target_model
node_etl_model -->|"presents mappings"| node_mapping_ui
node_mapping_ui -->|"updates mappings"| node_etl_model
node_etl_model -.->|"generates SQL"| node_sql_generator
node_etl_model -->|"generates specification"| node_word_output
node_etl_model -->|"generates markup"| node_markup_output
node_etl_model -->|"generates summary"| node_summary_output
node_etl_model -->|"generates framework"| node_test_output

click node_locations_ui "https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/gui/LocationsPanel.java"
click node_white_rabbit "https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/WhiteRabbitMain.java"
click node_source_scan "https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/scan/SourceDataScan.java"
click node_db_config "https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/databases/configuration/ScanConfiguration.java"
click node_db_handlers "https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/databases/JdbcStorageHandler.java"
click node_db_query "https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/databases/QueryResult.java"
click node_source_files "https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/scan/SourceDataScan.java"
click node_riah "https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/RabbitInAHatMain.java"
click node_source_model "https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/rabbitInAHat/dataModel/Database.java"
click node_etl_model "https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/dataModel/ETL.java"
click node_mapping_ui "https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/MappingPanel.java"
click node_target_model "https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/rabbitInAHat/dataModel/Database.java"
click node_sql_generator "https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/SQLGenerator.java"
click node_word_output "https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLWordDocumentGenerator.java"
click node_markup_output "https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLMarkupDocumentGenerator.java"
click node_summary_output "https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLSummaryGenerator.java"
click node_test_output "https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLTestFrameWorkGenerator.java"

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_locations_ui,node_white_rabbit,node_user toneBlue
class node_source_scan,node_db_config,node_db_handlers,node_db_query,node_source_files,node_source_database toneAmber
class node_riah,node_source_model,node_etl_model,node_mapping_ui,node_target_model,node_sql_generator toneMint
class node_word_output,node_markup_output,node_summary_output,node_test_output toneRose
class node_scan_report toneIndigo
```

## Components

### Scan setup

- [Source setup](https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/gui/LocationsPanel.java): `whiterabbit/src/main/java/org/ohdsi/whiterabbit/gui/LocationsPanel.java`
- [White Rabbit](https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/WhiteRabbitMain.java): `whiterabbit/src/main/java/org/ohdsi/whiterabbit/WhiteRabbitMain.java`

### Scan engine

- [Source scan](https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/scan/SourceDataScan.java): `whiterabbit/src/main/java/org/ohdsi/whiterabbit/scan/SourceDataScan.java`
- [DB settings](https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/databases/configuration/ScanConfiguration.java): `rabbit-core/src/main/java/org/ohdsi/databases/configuration/ScanConfiguration.java`
- [DB handlers](https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/databases/JdbcStorageHandler.java): `rabbit-core/src/main/java/org/ohdsi/databases/JdbcStorageHandler.java`
- [Query access](https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/databases/QueryResult.java): `rabbit-core/src/main/java/org/ohdsi/databases/QueryResult.java`
- [CSV/SAS input](https://github.com/ohdsi/whiterabbit/blob/master/whiterabbit/src/main/java/org/ohdsi/whiterabbit/scan/SourceDataScan.java): `whiterabbit/src/main/java/org/ohdsi/whiterabbit/scan/SourceDataScan.java`

### ETL design

- [Rabbit in a Hat](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/RabbitInAHatMain.java): `rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/RabbitInAHatMain.java`
- [Scanned model](https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/rabbitInAHat/dataModel/Database.java): `rabbit-core/src/main/java/org/ohdsi/rabbitInAHat/dataModel/Database.java`
- [ETL model](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/dataModel/ETL.java): `rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/dataModel/ETL.java`
- [Mapping editor](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/MappingPanel.java): `rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/MappingPanel.java`
- [OMOP target](https://github.com/ohdsi/whiterabbit/blob/master/rabbit-core/src/main/java/org/ohdsi/rabbitInAHat/dataModel/Database.java): `rabbit-core/src/main/java/org/ohdsi/rabbitInAHat/dataModel/Database.java`
- [SQL generator](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/SQLGenerator.java): `rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/SQLGenerator.java`

### ETL outputs

- [ETL specification](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLWordDocumentGenerator.java): `rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLWordDocumentGenerator.java`
- [Markup document](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLMarkupDocumentGenerator.java): `rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLMarkupDocumentGenerator.java`
- [ETL summary](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLSummaryGenerator.java): `rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLSummaryGenerator.java`
- [ETL test framework](https://github.com/ohdsi/whiterabbit/blob/master/rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLTestFrameWorkGenerator.java): `rabbitinahat/src/main/java/org/ohdsi/rabbitInAHat/ETLTestFrameWorkGenerator.java`

### Other components

- **User**
- **Source database**
- **Scan report**

## Connections

- User → White Rabbit: starts scan
- User → Source setup: configures source
- Source setup → DB settings: sets options
- White Rabbit → Source scan: runs scan
- Source scan → DB settings: uses settings
- Source scan → DB handlers: scans database
- DB handlers → Query access: executes queries
- Query access → Source database: reads rows
- Source scan → CSV/SAS input: scans files
- CSV/SAS input → Scan report: writes report
- Source scan → Scan report: writes report
- User → Rabbit in a Hat: designs ETL
- Rabbit in a Hat → Scanned model: loads scan report
- Scan report → Scanned model: provides scan data
- Rabbit in a Hat → ETL model: edits design
- Rabbit in a Hat → OMOP target: selects CDM
- ETL model → Mapping editor: presents mappings
- Mapping editor → ETL model: updates mappings
- ETL model → SQL generator: generates SQL
- ETL model → ETL specification: generates specification
- ETL model → Markup document: generates markup
- ETL model → ETL summary: generates summary
- ETL model → ETL test framework: generates framework