# monarch-initiative/phenol architecture

> Architecture diagram of the GitHub repository monarch-initiative/phenol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monarch-initiative/phenol
- Repository: https://github.com/monarch-initiative/phenol

## Overview

##### Project type and purpose
- This is a multi‑module Java library and CLI tool (“Phenol”) for loading, representing, and analyzing biological ontologies (HPO, MPO, GO, etc.) and phenotype annotations.
- It consists of five core Maven modules:
- phenol‑core: in‑memory ontology model, graph algorithms, similarity and score‐distribution utilities
- phenol‑io: file loaders/parsers for JSON, OBO, OBO‑Graph formats
- phenol‑annotations: domain‑specific loaders/parsers for HPO/MPO/Gene–disease annotations and temporal/metadata models
- phenol‑analysis: statistical and enrichment calculators (MGSA, hypergeometric tests, multiple test corrections)
- phenol‑cli: command‑line front end that ties all modules together for interactive or scripted use

##### File structure
- Top‑level: project root contains CI configs (GitHub workflows), Maven wrapper, docs/manual, and the multi‑module pom.xml.
- Each module lives in its own directory (pom.xml plus src/main/java and src/test/java).
- Packages within modules follow domain splits (e.g. org.monarchinitiative.phenol.graph, .io, .annotations, .analysis, .cli).
- Build and distribution helpers under contrib, documentation under docs and manual.

##### README for architectural clues
- README explicitly lists the modules, their responsibilities, and the recommended usage/dependencies.

- External Inputs/Outputs: JSON/OBO ontology files, annotation files, user CLI, external API clients
- Module Layer:
– phenol‑io (parsers/loaders)
– phenol‑core (ontology model & graph algorithms)
– phenol‑annotations (annotation domain logic)
– phenol‑analysis (statistics & enrichment algorithms)
– phenol‑cli (user‑facing commands)
- Infrastructure: Maven build, GitHub CI/CD, Javadoc/manual site, test suites

c. Architectural patterns & principles
- Layered (I/O → Model → Domain Logic → CLI)
- Modular Maven sub‑projects encapsulating cohesive responsibilities
- Dependency inversion: high‑level modules (analysis, CLI) depend only on well‑defined interfaces in lower modules

d. Technologies & frameworks
- Java 11+, Maven
- JSON/OBO parsing libs inside phenol‑io
- Graph algorithms implemented in phenol‑core
- Logback for logging (phenol‑cli resources)
- GitHub Actions for CI, ReadTheDocs/Sphinx for docs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs/Outputs
    subgraph "External Inputs/Outputs"
        JSON_OBO["JSON/OBO Ontology Files"]:::external
        ANNOT_FILES["Annotation Files"]:::external
        USER["User (CLI)"]:::external
    end

    %% Layers
    subgraph "I/O Layer" 
        IO["phenol-io\n(org.monarchinitiative.phenol.io)"]:::io
    end

    subgraph "Core/Model Layer"
        CORE["phenol-core\n(graph, ontology, similarity)"]:::core
    end

    subgraph "Annotation Domain Layer"
        ANNOT["phenol-annotations\n(org.monarchinitiative.phenol.annotations)"]:::annotations
    end

    subgraph "Analysis Layer"
        ANALYSIS["phenol-analysis\n(statistics, enrichment)"]:::analysis
    end

    subgraph "Presentation/CLI Layer"
        CLI["phenol-cli\n(org.monarchinitiative.phenol.cli)"]:::cli
    end

    %% Infrastructure
    subgraph "Infrastructure"
        MAVEN["Maven Multi-module (pom.xml)"]:::infra
        CI["GitHub Actions CI (.github/workflows/maven.yml)"]:::infra
        DOCS1["Docs Config (docs/conf.py)"]:::infra
        DOCS2["Manual Config (manual/source/conf.py)"]:::infra
        DIST1["Build Scripts (contrib/build_dist_master.sh)"]:::infra
        DIST2["Assembly Config (phenol-cli/src/assembly/dep.xml)"]:::infra
    end

    %% Data Flow
    JSON_OBO -->|"ontology data"| IO
    ANNOT_FILES -->|"annotation data"| IO
    IO -->|"OntologyGraph, JSON"| CORE
    CORE -->|"core model"| ANNOT
    CORE -->|"OntologyGraph"| ANALYSIS
    ANNOT -->|"TermAnnotations"| ANALYSIS
    IO -->|"parsers available"| CLI
    CORE -->|"model APIs"| CLI
    ANNOT -->|"annotation APIs"| CLI
    ANALYSIS -->|"enrichment results"| CLI
    CLI -->|"reports"| USER

    %% Infra relationships (dashed)
    MAVEN -.-> IO
    MAVEN -.-> CORE
    MAVEN -.-> ANNOT
    MAVEN -.-> ANALYSIS
    MAVEN -.-> CLI
    CI -.-> MAVEN
    DOCS1 -.-> MAVEN
    DOCS2 -.-> MAVEN
    DIST1 -.-> CLI
    DIST2 -.-> CLI

    %% Click Events
    click IO "https://github.com/monarch-initiative/phenol/tree/master/phenol-io/src/main/java/org/monarchinitiative/phenol/io"
    click CORE "https://github.com/monarch-initiative/phenol/tree/master/phenol-core/src/main/java/org/monarchinitiative/phenol/graph"
    click CORE "https://github.com/monarch-initiative/phenol/tree/master/phenol-core/src/main/java/org/monarchinitiative/phenol/ontology"
    click ANNOT "https://github.com/monarch-initiative/phenol/tree/master/phenol-annotations/src/main/java/org/monarchinitiative/phenol/annotations"
    click ANALYSIS "https://github.com/monarch-initiative/phenol/tree/master/phenol-analysis/src/main/java/org/monarchinitiative/phenol/analysis"
    click CLI "https://github.com/monarch-initiative/phenol/tree/master/phenol-cli/src/main/java/org/monarchinitiative/phenol/cli"
    click MAVEN "https://github.com/monarch-initiative/phenol/blob/master/pom.xml"
    click CI "https://github.com/monarch-initiative/phenol/blob/master/.github/workflows/maven.yml"
    click DOCS1 "https://github.com/monarch-initiative/phenol/blob/master/docs/conf.py"
    click DOCS2 "https://github.com/monarch-initiative/phenol/blob/master/manual/source/conf.py"
    click DIST1 "https://github.com/monarch-initiative/phenol/blob/master/contrib/build_dist_master.sh"
    click DIST2 "https://github.com/monarch-initiative/phenol/blob/master/phenol-cli/src/assembly/dep.xml"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef io fill:#bbdefb,stroke:#1e88e5,stroke-width:2px
    classDef core fill:#c8e6c9,stroke:#43a047,stroke-width:2px
    classDef annotations fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px
    classDef analysis fill:#e1bee7,stroke:#8e24aa,stroke-width:2px
    classDef cli fill:#eeeeee,stroke:#757575,stroke-width:2px
    classDef infra fill:#f0f0f0,stroke:#999,stroke-dasharray: 5 5,stroke-width:1px
```
