# hivdb/hivfacts architecture

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

- Interactive diagram: https://gitdiagram.com/hivdb/hivfacts
- Repository: https://github.com/hivdb/hivfacts

## Overview

##### Main Components

a) Data Processing Layer
- Separate modules for HIV-1 and HIV-2 data processing
- Data validation components
- Mutation analysis systems

b) Core Data Storage
- Structured data files (JSON, CSV, YAML)
- Algorithm definitions
- Reference data

c) Language-Specific Implementation Layer
- Java implementation
- Python implementation

##### Key Architectural Elements

**[Data Sources]**
- ↓
**[Data Processing Pipeline]**
- ↓
**[Core Data Storage] ←→ [Validation Layer]**
- ↓
**[Language Implementations]**
- ↓
**[Client Applications]**

##### Component Details

a) Data Processing Pipeline:
- APOBEC Filter Processing
- Mutation Analysis
- Statistical Analysis
- Data Format Converters (CSV/JSON/YAML)

b) Core Data Storage (organize in sections):
- Algorithms (/data/algorithms/)
- Mutation Data (/data/drms_*)
- Reference Data (genotypes, strains)
- Statistical Data (aapcnt, codonpcnt)

c) Validation Components:
- Sequence Validators
- Mutation Validators
- Quality Assurance Checks

##### Implementation Details

a) Java Implementation:
- Main classes (HIV.java, HIVDataLoader.java)
- Validation components
- Type-specific implementations

b) Python Implementation:
- Main modules (hivaapcnt.py, hivapobec.py)
- Data access patterns
- Processing components

##### Key Relationships to Highlight

- Data processing workflows
- Validation chains
- Implementation interfaces
- Configuration management
- Version control points

Remember to include notes about the quality assurance criteria mentioned in the README, particularly the sequence QA criteria and APOBEC cutoff values, as these are critical to the system's operation.

This architecture should emphasize the system's ability to handle both HIV-1 and HIV-2 data while maintaining strict validation and quality control throughout the processing pipeline.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Data Sources"
        DS1[External Data Sources]
    end

    subgraph "Data Processing Pipeline"
        DPP1["APOBEC Filter Processing"]:::processing
        DPP2["Statistical Analysis"]:::processing
        DPP3["Data Format Converters"]:::processing
        
        DPP1 --> DPP2
        DPP2 --> DPP3
    end

    subgraph "Core Data Storage"
        CDS1["Algorithms"]:::storage
        CDS2["Mutation Data"]:::storage
        CDS3["Reference Data"]:::storage
        CDS4["Statistical Data"]:::storage
    end

    subgraph "Validation Layer"
        VL1["Sequence Validators"]:::validation
        VL2["Mutation Validators"]:::validation
        VL3["Quality Assurance"]:::validation
    end

    subgraph "Language Implementations"
        subgraph "Java Implementation"
            JI1["HIV Core"]:::implementation
            JI2["HIV-2 Specific"]:::implementation
            JI3["Data Loader"]:::implementation
        end

        subgraph "Python Implementation"
            PI1["APOBEC Analysis"]:::implementation
            PI2["Amino Acid Analysis"]:::implementation
            PI3["Codon Analysis"]:::implementation
        end
    end

    subgraph "Configuration"
        CF1["HIV-1 Config"]:::config
        CF2["HIV-2 Config"]:::config
    end

    DS1 --> DPP1
    DPP3 --> CDS1
    DPP3 --> CDS2
    DPP3 --> CDS3
    DPP3 --> CDS4
    
    CDS1 <--> VL1
    CDS2 <--> VL2
    CDS3 <--> VL3
    
    VL1 --> JI1
    VL2 --> JI2
    VL3 --> JI3
    
    VL1 --> PI1
    VL2 --> PI2
    VL3 --> PI3

    CF1 --> JI1
    CF2 --> JI2

    %% Click events for component mapping
    click DPP1 "https://github.com/hivdb/hivfacts/blob/main/scripts/apply_apobec_filter.py"
    click DPP2 "https://github.com/hivdb/hivfacts/blob/main/scripts/basicstat.py"
    click DPP3 "https://github.com/hivdb/hivfacts/blob/main/scripts/csv2json.py"
    click CDS1 "https://github.com/hivdb/hivfacts/tree/main/data/algorithms/"
    click CDS2 "https://github.com/hivdb/hivfacts/blob/main/data/drms_hiv1.json"
    click CDS3 "https://github.com/hivdb/hivfacts/tree/main/data/genotypes/"
    click CDS4 "https://github.com/hivdb/hivfacts/tree/main/data/aapcnt/"
    click JI1 "https://github.com/hivdb/hivfacts/blob/main/hivfacts-java/src/main/java/edu/stanford/hivdb/hivfacts/HIV.java"
    click JI2 "https://github.com/hivdb/hivfacts/blob/main/hivfacts-java/src/main/java/edu/stanford/hivdb/hivfacts/hiv2/HIV2.java"
    click JI3 "https://github.com/hivdb/hivfacts/blob/main/hivfacts-java/src/main/java/edu/stanford/hivdb/hivfacts/HIVDataLoader.java"
    click PI1 "https://github.com/hivdb/hivfacts/blob/main/hivfacts-python/hivfacts/hivapobec.py"
    click PI2 "https://github.com/hivdb/hivfacts/blob/main/hivfacts-python/hivfacts/hivaapcnt.py"
    click PI3 "https://github.com/hivdb/hivfacts/blob/main/hivfacts-python/hivfacts/hivcodonpcnt.py"
    click VL1 "https://github.com/hivdb/hivfacts/blob/main/hivfacts-java/src/main/java/edu/stanford/hivdb/hivfacts/HIVDefaultSequenceValidator.java"
    click VL2 "https://github.com/hivdb/hivfacts/blob/main/hivfacts-java/src/main/java/edu/stanford/hivdb/hivfacts/HIVDefaultMutationsValidator.java"
    click VL3 "https://github.com/hivdb/hivfacts/blob/main/hivfacts-java/src/main/java/edu/stanford/hivdb/hivfacts/hiv2/HIV2DefaultSequenceValidator.java"
    click CF1 "https://github.com/hivdb/hivfacts/blob/main/data/alignment-config_hiv1.json"
    click CF2 "https://github.com/hivdb/hivfacts/blob/main/data/alignment-config_hiv2.json"

    classDef processing fill:#90EE90
    classDef storage fill:#87CEEB
    classDef validation fill:#FFD700
    classDef implementation fill:#FFA500
    classDef config fill:#D3D3D3

    %% Legend
    subgraph Legend
        L1["Processing"]:::processing
        L2["Storage"]:::storage
        L3["Validation"]:::validation
        L4["Implementation"]:::implementation
        L5["Configuration"]:::config
    end
```
