# tamil-phy/nhs-healthsign architecture

> Architecture diagram of the GitHub repository tamil-phy/nhs-healthsign, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tamil-phy/nhs-healthsign
- Repository: https://github.com/tamil-phy/nhs-healthsign

## Overview

##### File structure
- Top-level scripts:
- pdf2md.py – PDF → Markdown conversion using Docling.
- main.py – Core analysis engine (disease screening, vitals analysis, timeline monitoring).
- streamlit-ui.py – Streamlit dashboard for interactive exploration.
- Config directories/files:
- INTERESTED_READCODES.json, red_flag_read_codes_subset.json – clinical codes for disease screening.
- INTERESTED_VITALS.json – vital sign definitions and units.
- secrets.json – API keys / sensitive settings.
- Output directory:
- output_trial/ – JSON artifacts (code_matches.json, timeline.json, vital_matches.json) from a sample run.
- Supporting files:
- INTERESTED_*.json – domain data driving the analysis.
- main.py and pdf2md.py reference these configs.

##### Extract README insights
- The pipeline has three phases: ingestion (PDF → Markdown), processing (screen codes, vitals, timelines), and presentation (Streamlit).
- Dependencies include Python, Docling, fuzzywuzzy, OpenAI (if used), and Streamlit.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Layer"
        PDFs["NHS PDF Reports"]:::artifact
    end

    subgraph "Data Processing Pipeline"
        Parser["PDF Parsing Module\n(pdf2md.py + Docling)"]:::script
        Docling["Docling"]:::external
        Parser -->|PDF| ParserOut["Markdown Files"]:::artifact
        Parser --> Docling

        Analysis["Analysis Engine\n(main.py)"]:::script

        subgraph "Analysis Subcomponents"
            Scanner["Read-code Scanner\n(fuzzywuzzy)"]:::script
            VitalAnalyzer["Vital-sign Analyzer"]:::script
            Timeline["Timeline Monitor"]:::script
        end

        ConfigCodes["INTERESTED_READCODES.json"]:::config
        ConfigRedFlag["red_flag_read_codes_subset.json"]:::config
        ConfigVitals["INTERESTED_VITALS.json"]:::config

        ParserOut --> Analysis
        ConfigCodes --> Analysis
        ConfigRedFlag --> Analysis
        ConfigVitals --> Analysis

        Analysis -->|code_matches.json| OutCode["code_matches.json"]:::artifact
        Analysis -->|timeline.json| OutTimeline["timeline.json"]:::artifact
        Analysis -->|vital_matches.json| OutVital["vital_matches.json"]:::artifact
    end

    subgraph "Presentation Layer"
        UI["Interactive UI\n(streamlit-ui.py)"]:::ui
        OutCode --> UI
        OutTimeline --> UI
        OutVital --> UI
        ConfigSecrets["secrets.json"]:::config
        ConfigSecrets --> UI
    end

    %% Click Events
    click Parser "https://github.com/tamil-phy/nhs-healthsign/blob/main/pdf2md.py"
    click Analysis "https://github.com/tamil-phy/nhs-healthsign/blob/main/main.py"
    click ConfigCodes "https://github.com/tamil-phy/nhs-healthsign/blob/main/INTERESTED_READCODES.json"
    click ConfigRedFlag "https://github.com/tamil-phy/nhs-healthsign/blob/main/red_flag_read_codes_subset.json"
    click ConfigVitals "https://github.com/tamil-phy/nhs-healthsign/blob/main/INTERESTED_VITALS.json"
    click ConfigSecrets "https://github.com/tamil-phy/nhs-healthsign/blob/main/secrets.json"
    click OutCode "https://github.com/tamil-phy/nhs-healthsign/blob/main/output_trial/code_matches.json"
    click OutTimeline "https://github.com/tamil-phy/nhs-healthsign/blob/main/output_trial/timeline.json"
    click OutVital "https://github.com/tamil-phy/nhs-healthsign/blob/main/output_trial/vital_matches.json"
    click UI "https://github.com/tamil-phy/nhs-healthsign/blob/main/streamlit-ui.py"

    %% Styles
    classDef script fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef config fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef artifact fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef ui fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#000,stroke-width:1px,stroke-dasharray:5 5;
```
