# dccc-nova/genlister architecture

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

- Interactive diagram: https://gitdiagram.com/dccc-nova/genlister
- Repository: https://github.com/dccc-nova/genlister

## Overview

##### Project Type and Purpose
- Genlister is not a full-stack web application but rather a specialized tool that operates on flat files (CSV) representing gene lists.
- Its purpose is to maintain gene lists for various genetic categories (e.g., germline, fusion, SNV, CNV) by validating individual department lists and automatically aggregating them into “combined.csv” files.

##### Analyzing the File Structure
- Top-level directories like “germline” contain the domain data (CSV files for different departments) and combined CSV files.
- The “src” directory houses the main logic inside the “genlister” package with modules such as:
- core.py – likely includes shared logic for processing the gene list data.
- create_combined.py – responsible for generating the “combined.csv” files.
- validate.py – handles validation logic for the CSV files.
- The “.github” folder with the workflows (e.g., validation.yml) indicates that CI is set up to automatically run validations on changes.
- Supporting files like pyproject.toml and uv.lock confirm that this is a Python project with dependency management in place.

##### Key Components
a. Data Storage/Inputs:
- CSV files stored in the “germline” directory.
- Individual department folders (afmd, gm, moma, ouh, vejle) containing raw gene list CSVs.
b. Processing Modules:
- The Core Module (core.py) for shared functionality.
- The Create Combined Module (create_combined.py) showing the aggregation of separate gene lists.
- The Validation Module (validate.py) for verifying CSV file integrity.
c. CI/CD Pipeline:
- A component representing GitHub Actions (as seen in the “.github/workflows/validation.yml”) that automatically triggers the validation process when there are changes to the gene lists.
d. Optional Components:
- While the “scripts” folder is present, if it’s simply an utility or initialization layer, you may combine it with the core processing modules unless it explicitly defines separate functionality.

##### Representing Relationships and Interactions
- The Validation Module (validate.py) ensures that every input CSV meets quality standards.
- Once individual files are validated, the Create Combined Module (create_combined.py) aggregates them into a “combined.csv”.

##### Architectural Patterns and Technologies
- A modular design that separates data input, processing (validation and aggregation), and continuous integration.
- Use of Python for scripting and automation, CSV files as the primary data store, and GitHub Actions for CI ensuring data integrity.
- If any libraries or frameworks are mentioned in pyproject.toml, include a note for those dependencies (even if not explicitly listed in our file tree).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipeline
    CIPipeline["CI/CD Pipeline (GitHub Actions - validation.yml)"]:::ci

    %% Data Layer: CSV Files from germline Department Folders
    subgraph "CSV Data (germline Department Files)"
        CSV_A["afmd.csv"]:::data
        CSV_B["gm.csv"]:::data
        CSV_C["gener.csv"]:::data
        CSV_D["ouh.csv"]:::data
        CSV_E["vejle.csv"]:::data
    end

    %% Processing Modules
    subgraph "Genlister Processing Modules"
        Core["Core Logic (core.py)"]:::processing
        Valid["Validation Module (validate.py)"]:::processing
        Combine["Combination Module (create_combined.py)"]:::processing
    end

    %% Connections
    CIPipeline -->|"trigger"| Valid

    CSV_A -->|"input"| Valid
    CSV_B -->|"input"| Valid
    CSV_C -->|"input"| Valid
    CSV_D -->|"input"| Valid
    CSV_E -->|"input"| Valid

    Valid -->|"aggregate"| Combine

    Core -->|"orchestrates"| Valid
    Core -->|"orchestrates"| Combine

    %% Click Events
    click CSV_A "https://github.com/dccc-nova/genlister/tree/main/germline/afmd"
    click CSV_B "https://github.com/dccc-nova/genlister/tree/main/germline/gm"
    click CSV_C "https://github.com/dccc-nova/genlister/tree/main/germline/moma"
    click CSV_D "https://github.com/dccc-nova/genlister/tree/main/germline/ouh"
    click CSV_E "https://github.com/dccc-nova/genlister/tree/main/germline/vejle"
    click Core "https://github.com/dccc-nova/genlister/blob/main/src/genlister/core.py"
    click Valid "https://github.com/dccc-nova/genlister/blob/main/src/genlister/validate.py"
    click Combine "https://github.com/dccc-nova/genlister/blob/main/src/genlister/create_combined.py"
    click CIPipeline "https://github.com/dccc-nova/genlister/blob/main/.github/workflows/validation.yml"

    %% Styles
    classDef data fill:#F4D03F,stroke:#F39C12,stroke-width:2px;
    classDef processing fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef ci fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
```
