# patrickthealba/prostate-cancer-phenotyping architecture

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

- Interactive diagram: https://gitdiagram.com/patrickthealba/prostate-cancer-phenotyping
- Repository: https://github.com/patrickthealba/prostate-cancer-phenotyping

## Overview

##### Project type and purpose
- This is a specialized NLP pipeline tool for extracting metastatic prostate cancer and castration-resistant prostate cancer diagnoses from clinical text.
- It builds on the Leo framework (a UIMA AS–based NLP pipeline) and provides configurable readers and listeners to integrate with file systems or databases.

##### File structure
- Top-level directories:
- config/ – Groovy configuration for the UIMA AS client, service, readers, listeners, and annotator descriptors.
- data/input/ – Sample text input files.
- generated-types/ – Auto-generated Java and XML type system definitions for all annotation types.
- src/main/java/ – Core Java code: LeoClient, LeoServiceMetastasis, pipeline definitions, annotator implementations, listener logic.
- src/main/java/resources/ – Pattern, rule, and stopword files used by regex and pattern annotators.
- lib/, pom.xml – Maven build and external dependencies (Leo, UIMA AS).

##### Key insights from the README
- The entry point is a UIMA AS service (“LeoServiceMetastasis”) invoked by a client (“LeoClient”).
- Readers (file or database) submit CASes to the UIMA AS broker; the service picks up CASes, runs the Metastasis_Pipeline, then dispatches results to configured listeners (XMI file writer, CSV writer, database writer).
- The pipeline is a linear sequence of annotators: Regex → Merge → Pattern → AnchoredSentence → Context → MetastasisLogic.

##### Main components
a. Input layer (Collection Readers)
- FileCollectionReaderConfig
- DatabaseCollectionReaderConfig / BatchDatabaseCollectionReaderConfig
b. UIMA AS infrastructure
- UIMA AS Broker (message queue)
- LeoClient (pushes CAS to broker)
- LeoServiceMetastasis (pulls CAS from broker, runs pipeline)
c. NLP Pipeline (Metastasis_Pipeline)
1. RegexAnnotator (Metastasis terms, exclude terms)
2. MergeAnnotator (overlap resolution)
3. AnnotationPatternAnnotator (hormone, medication, other patterns)
4. AnchoredSentenceAnnotator (context window creation)
5. ContextAnnotator (negation, experiencer, temporality)
6. MetastasisLogic (final mPCa_flag, castrate_resistant output types)
d. Type System & generated-types
- TypeSystem.java + generated-types/classes and resources (TypeSystem.xml)
e. Output layer (Listeners)
- SimpleXmiListenerConfig → writes XMI files
- CsvListenerConfig → writes CSV
- MetastasisDatabaseListenerConfig → writes back to database

##### Relationships and data flow
- Readers → (CAS) → UIMA AS Broker → LeoServiceMetastasis → (invokes) Metastasis_Pipeline → (enriched CAS) → Listeners → output sinks (filesystem, DB).
- LeoClient is an alternate front end that can submit CAS to the broker programmatically.
- Configuration files (Groovy) parameterize readers, listeners, and service settings (host, port).
- The pipeline reads resource patterns and rules from src/main/java/resources at runtime.

##### Architectural patterns and principles
- Pipeline pattern (linear chain of annotators operating on a shared CAS).
- Configuration-driven design (readers/listeners/annotators wired via Groovy scripts).
- Separation of concerns:
- Readers handle input retrieval
- Annotators perform text analysis
- Listeners handle output persistence
- Type system defines shared data schema
- Extensibility points: add new annotators, readers, or listeners by implementing UIMA components and updating configs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Input Readers
    subgraph "Layer 1: Input Readers"
        FCR["FileCollectionReaderConfig"]:::config
        click FCR "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/config/readers/FileCollectionReaderConfig.groovy"
        DBR["DatabaseCollectionReaderConfig"]:::config
        click DBR "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/config/readers/DatabaseCollectionReader.groovy"
        BDBR["BatchDatabaseCollectionReaderConfig"]:::config
        click BDBR "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/config/readers/BatchDatabaseCollectionReaderExample.groovy"
        FS["File System"]:::external
        DBExt["Database"]:::external
        FCR -->|reads files| FS
        DBR -->|reads DB| DBExt
        BDBR -->|reads DB| DBExt
    end

    %% Layer 2: UIMA AS Infrastructure
    subgraph "Layer 2: UIMA AS Infrastructure"
        Client["LeoClient"]:::java
        click Client "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/gov/va/vinci/LeoClient.java"
        Broker["UIMA AS Broker"]:::external
        Service["LeoServiceMetastasis"]:::java
        click Service "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/gov/va/vinci/LeoServiceMetastasis.java"
        FCR -->|submit CAS| Broker
        DBR -->|submit CAS| Broker
        BDBR -->|submit CAS| Broker
        Client -->|push CAS| Broker
        Broker -->|pull CAS| Service
    end

    %% Layer 3: Metastasis Pipeline
    subgraph "Layer 3: Metastasis Pipeline"
        BasePL["BasePipeline"]:::java
        click BasePL "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/gov/va/vinci/pipeline/BasePipeline.java"
        MetaPipe["Metastasis_Pipeline"]:::java
        click MetaPipe "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/gov/va/vinci/pipeline/Metastasis_Pipeline.java"
        RA["RegexAnnotator"]:::java
        MA["MergeAnnotator"]:::java
        PA["AnnotationPatternAnnotator"]:::java
        AS["AnchoredSentenceAnnotator"]:::java
        CA["ContextAnnotator"]:::java
        ML["MetastasisLogic"]:::java
        click ML "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/gov/va/vinci/ae/MetastasisLogic.java"
        Service -->|invoke pipeline| MetaPipe
        MetaPipe --> RA --> MA --> PA --> AS --> CA --> ML
    end

    %% Layer 4: Type System
    subgraph "Layer 4: Type System"
        TSJava["TypeSystem.java"]:::java
        click TSJava "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/gov/va/vinci/TypeSystem.java"
        TSXML["TypeSystem.xml"]:::xml
        click TSXML "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/generated-types/resources/types/TypeSystem.xml"
        GenTypes["Generated Types"]:::java
        click GenTypes "https://github.com/patrickthealba/prostate-cancer-phenotyping/tree/main/generated-types/src/"
        click GenTypes "https://github.com/patrickthealba/prostate-cancer-phenotyping/tree/main/generated-types/classes/"
        TSJava --> GenTypes
        TSXML --> GenTypes
        MetaPipe -->|uses types| GenTypes
    end

    %% Layer 5: Output Listeners
    subgraph "Layer 5: Output Listeners"
        XMIConfig["SimpleXmiListenerConfig"]:::config
        click XMIConfig "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/config/listeners/SimpleXmiListenerConfig.groovy"
        CSVConfig["CsvListenerConfig"]:::config
        click CSVConfig "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/config/listeners/CsvListenerConfig.groovy"
        DBConfig["MetastasisDatabaseListenerConfig"]:::config
        click DBConfig "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/config/listeners/MetastasisDatabaseListenerConfig.groovy"
        XMIListener["BasicXmiListener"]:::java
        CSVListener["BasicCsvListener"]:::java
        click CSVListener "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/gov/va/vinci/listeners/BasicCsvListener.java"
        DBListener["BasicDatabaseListener"]:::java
        click DBListener "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/gov/va/vinci/listeners/BasicDatabaseListener.java"
        ListenerBase["ListenerLogic"]:::java
        click ListenerBase "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/gov/va/vinci/listeners/ListenerLogic.java"
        ML --> XMIConfig
        ML --> CSVConfig
        ML --> DBConfig
        XMIConfig --> XMIListener -->|writes XMI| FS
        CSVConfig --> CSVListener -->|writes CSV| FS
        DBConfig --> DBListener -->|writes SQL| DBExt
    end

    %% Resources
    subgraph "Resources"
        PPat["Metastasis_Pattern.pattern"]:::resource
        click PPat "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/resources/Metastasis_Pattern.pattern"
        HPat["Metastasis_Hormone_Pattern.pattern"]:::resource
        click HPat "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/resources/Metastasis_Hormone_Pattern.pattern"
        MPat["Metastasis_Medication_Pattern.pattern"]:::resource
        click MPat "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/resources/Metastasis_Medication_Pattern.pattern"
        NPat["Metastasis_Negation_Pattern.pattern"]:::resource
        click NPat "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/resources/Metastasis_Negation_Pattern.pattern"
        ExPat["Exclude_Pattern.pattern"]:::resource
        click ExPat "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/resources/Exclude_Pattern.pattern"
        StopW["stopwords.txt"]:::resource
        click StopW "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/resources/stopwords.txt"
        ExGro["Exclude.groovy"]:::resource
        click ExGro "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/resources/Exclude.groovy"
        CRules["contextRules.txt"]:::resource
        click CRules "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/resources/contextRules.txt"
        SecHdr["sectionHeaders.groovy"]:::resource
        click SecHdr "https://github.com/patrickthealba/prostate-cancer-phenotyping/blob/main/src/main/java/resources/sectionHeaders.groovy"
        RA -.-> PPat
        MA -.-> ExPat
        PA -.-> HPat
        PA -.-> MPat
        CA -.-> NPat
        CA -.-> CRules
        AS -.-> SecHdr
    end

    %% Styles
    classDef java fill:#ADD8E6,stroke:#000,color:#000;
    classDef external fill:#90EE90,stroke:#000,color:#000;
    classDef config fill:#FFFFE0,stroke:#000,color:#000;
    classDef resource fill:#D8BFD8,stroke:#000,color:#000;
    classDef xml fill:#EEE5DE,stroke:#000,color:#000;
```
