# wwpdb/py-wwpdb_apps_chem_ref_data architecture

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

- Interactive diagram: https://gitdiagram.com/wwpdb/py-wwpdb_apps_chem_ref_data
- Repository: https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data

## Overview

ChemRefData is a web application for managing and searching the chemical reference database. Users submit requests through the web app, which dispatches search or report work and returns rendered results; administrators can also synchronize reference files and load database data. The graph preserves search/indexing, component and BIRD reports, depiction, and repository-maintenance capabilities. Relationships are limited to README statements, shown excerpts, and SOURCE INDEX references; unsampled implementation details are not treated as verified calls.

Main entry points: [`wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py) (Request dispatch), [`wwpdb/apps/chem_ref_data/search/ChemRefSearch.py`](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearch.py) (Search entry), [`wwpdb/apps/chem_ref_data/search/ChemRefSearchBase.py`](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearchBase.py) (Search execution), [`wwpdb/apps/chem_ref_data/report/BirdReport.py`](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/report/BirdReport.py) (BIRD reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Web entry"]
  node_web["Request dispatch"]
end

subgraph group_search["Search"]
  node_search_api["Search entry<br/>[ChemRefSearch.py]"]
  node_search_engine["Search execution"]
  node_query_defs["Query definitions"]
  node_chem_index["Chemical index"]
  node_search_render["Search rendering"]
  node_duplicate_search["Duplicate search"]
end

subgraph group_reports["Reports and display"]
  node_bird_report["BIRD reports<br/>[BirdReport.py]"]
  node_component_report["Component reports<br/>[ChemCompReport.py]"]
  node_report_utils["Report utilities<br/>[ReportUtils.py]"]
  node_report_render["Report rendering"]
  node_page_shell["Page shell"]
end

subgraph group_maintenance["Data maintenance"]
  node_cvs["CVS synchronization"]
  node_db_load["Database loading"]
  node_data_files["Reference file generation"]
  node_download["File download<br/>[DownloadUtils.py]"]
  node_data_store[("Reference repositories")]
end

node_user(("User"))

node_user -->|"submits requests"| node_web
node_web -->|"dispatches searches"| node_search_api
node_search_api -->|"delegates to"| node_search_engine
node_search_api -->|"uses definitions"| node_query_defs
node_search_engine -->|"uses index"| node_chem_index
node_web -->|"renders results"| node_search_render
node_web -->|"requests reports"| node_bird_report
node_web -->|"requests reports"| node_component_report
node_web -->|"renders reports"| node_report_render
node_bird_report -->|"uses utilities"| node_report_utils
node_component_report -->|"uses utilities"| node_report_utils
node_report_render -->|"uses page shell"| node_page_shell
node_web -->|"synchronizes data"| node_cvs
node_web -->|"loads data"| node_db_load
node_web -->|"updates files"| node_data_files
node_web -->|"fetches files"| node_download
node_cvs -->|"syncs repository"| node_data_store
node_db_load -.->|"loads reference data"| node_data_store

click node_web "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py"
click node_search_api "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearch.py"
click node_search_engine "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearchBase.py"
click node_query_defs "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearchDef.py"
click node_chem_index "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemCompSearchIndexUtils.py"
click node_search_render "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearchDepictBootstrap.py"
click node_duplicate_search "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearchDuplicates.py"
click node_bird_report "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/report/BirdReport.py"
click node_component_report "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/report/ChemCompReport.py"
click node_report_utils "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/report/ReportUtils.py"
click node_report_render "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/report/ChemRefReportDepictBootstrap.py"
click node_page_shell "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/depict/ChemRefDataDepictBootstrap.py"
click node_cvs "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/utils/ChemRefDataCvsUtils.py"
click node_db_load "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/utils/ChemRefDataDbUtils.py"
click node_data_files "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/utils/ChemRefDataMiscUtils.py"
click node_download "https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/utils/DownloadUtils.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_web,node_user toneBlue
class node_search_api,node_search_engine,node_query_defs,node_chem_index,node_search_render,node_duplicate_search toneAmber
class node_bird_report,node_component_report,node_report_utils,node_report_render,node_page_shell toneMint
class node_cvs,node_db_load,node_data_files,node_download,node_data_store toneRose
```

## Components

### Web entry

- [Request dispatch](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py): `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`

### Search

- [Search entry](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearch.py): `wwpdb/apps/chem_ref_data/search/ChemRefSearch.py`
- [Search execution](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearchBase.py): `wwpdb/apps/chem_ref_data/search/ChemRefSearchBase.py`
- [Query definitions](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearchDef.py): `wwpdb/apps/chem_ref_data/search/ChemRefSearchDef.py`
- [Chemical index](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemCompSearchIndexUtils.py): `wwpdb/apps/chem_ref_data/search/ChemCompSearchIndexUtils.py`
- [Search rendering](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearchDepictBootstrap.py): `wwpdb/apps/chem_ref_data/search/ChemRefSearchDepictBootstrap.py`
- [Duplicate search](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/search/ChemRefSearchDuplicates.py): `wwpdb/apps/chem_ref_data/search/ChemRefSearchDuplicates.py`

### Reports and display

- [BIRD reports](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/report/BirdReport.py): `wwpdb/apps/chem_ref_data/report/BirdReport.py`
- [Component reports](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/report/ChemCompReport.py): `wwpdb/apps/chem_ref_data/report/ChemCompReport.py`
- [Report utilities](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/report/ReportUtils.py): `wwpdb/apps/chem_ref_data/report/ReportUtils.py`
- [Report rendering](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/report/ChemRefReportDepictBootstrap.py): `wwpdb/apps/chem_ref_data/report/ChemRefReportDepictBootstrap.py`
- [Page shell](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/depict/ChemRefDataDepictBootstrap.py): `wwpdb/apps/chem_ref_data/depict/ChemRefDataDepictBootstrap.py`

### Data maintenance

- [CVS synchronization](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/utils/ChemRefDataCvsUtils.py): `wwpdb/apps/chem_ref_data/utils/ChemRefDataCvsUtils.py`
- [Database loading](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/utils/ChemRefDataDbUtils.py): `wwpdb/apps/chem_ref_data/utils/ChemRefDataDbUtils.py`
- [Reference file generation](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/utils/ChemRefDataMiscUtils.py): `wwpdb/apps/chem_ref_data/utils/ChemRefDataMiscUtils.py`
- [File download](https://github.com/wwpdb/py-wwpdb_apps_chem_ref_data/blob/master/wwpdb/apps/chem_ref_data/utils/DownloadUtils.py): `wwpdb/apps/chem_ref_data/utils/DownloadUtils.py`
- **Reference repositories**

### Other components

- **User**

## Connections

- User → Request dispatch: submits requests (evidence: `README.md`)
- Request dispatch → Search entry: dispatches searches (evidence: `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`)
- Search entry → Search execution: delegates to (evidence: `wwpdb/apps/chem_ref_data/search/ChemRefSearch.py`)
- Search entry → Query definitions: uses definitions (evidence: `wwpdb/apps/chem_ref_data/search/ChemRefSearch.py`)
- Search execution → Chemical index: uses index (evidence: `wwpdb/apps/chem_ref_data/search/ChemRefSearchBase.py`)
- Request dispatch → Search rendering: renders results (evidence: `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`)
- Request dispatch → BIRD reports: requests reports (evidence: `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`)
- Request dispatch → Component reports: requests reports (evidence: `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`)
- Request dispatch → Report rendering: renders reports (evidence: `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`)
- BIRD reports → Report utilities: uses utilities (evidence: `wwpdb/apps/chem_ref_data/report/BirdReport.py`)
- Component reports → Report utilities: uses utilities (evidence: `wwpdb/apps/chem_ref_data/report/ChemCompReport.py`)
- Report rendering → Page shell: uses page shell (evidence: `wwpdb/apps/chem_ref_data/report/ChemRefReportDepictBootstrap.py`)
- Request dispatch → CVS synchronization: synchronizes data (evidence: `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`)
- Request dispatch → Database loading: loads data (evidence: `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`)
- Request dispatch → Reference file generation: updates files (evidence: `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`)
- Request dispatch → File download: fetches files (evidence: `wwpdb/apps/chem_ref_data/webapp/ChemRefDataWebApp.py`)
- CVS synchronization → Reference repositories: syncs repository (evidence: `wwpdb/apps/chem_ref_data/utils/ChemRefDataCvsUtils.py`)
- Database loading → Reference repositories: loads reference data
