# verisimilitudex/dnanalyzer architecture

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

- Interactive diagram: https://gitdiagram.com/verisimilitudex/dnanalyzer
- Repository: https://github.com/verisimilitudex/dnanalyzer

## Overview

##### Project Type and Purpose
- DNAnalyzer is a full-stack, Java-based, machine learning–powered DNA analysis platform. It supports on-device genomic analysis through multiple interfaces (web, CLI, and GUI), enabling users to process DNA data and perform tasks like reading frame analysis, mutation identification, and codon translation.
- The README emphasizes privacy (no centralized database), efficient on-device computation, and accessibility via various frontends. This platform clearly separates core bioinformatics logic from diverse user interfaces.

##### Out the Main Components
- Presentation Layers:
- Web: The “web” directory contains the web frontend assets (HTML, CSS, JavaScript, server-side pages) for user interaction.
- GUI: Located under src/main/java/DNAnalyzer/ui/gui (along with its corresponding FXML files and controllers in src/main/resources), this component manages the graphical user interface.
- CLI: Found under src/main/java/DNAnalyzer/ui/cli, this layer handles command-line interactions for automation/scripting.

- Application/Adapter (Interface) Layer:
- API/Controllers: Classes in the “adapter” package (e.g., AnalyseController, ApiKeyController, FileController) and the “api” package (DNAnalyzerApiController) act as entry points. They receive external input (from web requests, CLI commands, etc.) and invoke the core use cases.

- Domain/Core Business Logic:
- Core Package: Contains DNAnalyzer’s central functionality (e.g., DNAAnalysis, DNAMutation, DNADataUploader). The “port/in” subpackage outlines use case interfaces like AnalyzeDnaUseCase, GetApiKeyUseCase, and SetApiKeyUseCase. This design is similar to a Clean Architecture approach where business rules remain independent.
- Specialized Modules: The “readingframe” package deals with gene coding regions and reading frame analysis (e.g., ReadingFrameAnalyzer, PoissonCalculator), while “data” packages handle parsing and codon data (e.g., CodonDataUtils).

- Utility Components:
- Under “utils” (both core and specialized for protein and AI), helper functions support domain operations (e.g., BasePairCounter, DNATools, ProteinAnalysis). They often provide lower-level algorithms that the core and adapters rely on.

- Infrastructure/Integration:
- Lib: Contains pre-built library files (jar, rar, zip) which might be used in deployments or by external tools.
- Build & CI/CD: Gradle build scripts (build.gradle, settings.gradle.kts, gradlew scripts) and GitHub Actions/workflows illustrate the build, test, and deployment pipelines.
- Installer: Scripting files for automated installations (PowerShell scripts for Java installation, etc.) which support environment set-up.

##### Relationships and Interactions
- Data flow starts at the Presentation layer (Web, CLI, or GUI) where input is received by the system.
- Input flows to the Adapter/Interface Layer (controllers in “adapter” and “api”), which then call the relevant use cases defined in the core’s “port/in” interfaces.
- The Core Business Logic implements these use cases to perform DNA analysis. It interacts with various submodules (readingframe logic, codon analysis, parsing) and util functions.
- Finally, results are packaged and sent back through the adapters to the specific user interface for display or further action.
- Auxiliary flows like API-key authentication, error handling (e.g., ApiKeyMissingException), and file processing add additional layers of dependency.

##### Architectural Patterns and Design Principles
- Clean/Hexagonal Architecture: Separation of concerns is clear between the UI (adapters) and the domain logic. The “port/in” pattern further underlines the use of dependency inversion where controllers pass data to use-case implementations.
- Modularity: Each folder/package (UI, core, utils, data, readingframe) encapsulates a clear responsibility, facilitating future expansion (like integrating a SQL database).

##### Detailed Elements
- Component Labels: Tag each module/component with its package or purpose (e.g., “DNAnalyzerApplication”, “ReadingFrameAnalyzer”, “BasePairCounter”).
- How UI components (Web/CLI/GUI) invoke controllers.
- How controllers interact with core use cases through the “port/in” interfaces.
- How the core logic utilizes utility classes and domain models.

- A clear separation of layers: Presentation (Web, GUI, CLI), Application/Adapters (Controllers/API), Domain (Core DNA analysis, reading frame, data processing), and Utilities/Infrastructure.
- Labels that make it obvious which Java packages or components are being represented (e.g., “adapter”, “core/port/in”, “utils”), along with any external build or installer tools.
- A note or annotation for future planned components (e.g., SQL database, enhanced neural network integration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        Web["Web Frontend"]:::presentation
        GUI["GUI Frontend"]:::presentation
        CLI["CLI Frontend"]:::presentation
    end

    subgraph "Application/Adapter Layer"
        Adapter["Adapter Controllers"]:::adapter
        API["API Controller"]:::adapter
    end

    subgraph "Domain Layer"
        Core["Core Business Logic"]:::domain
        Port["Port/in Interfaces"]:::domain
        RF["Reading Frame Analysis Module"]:::domain
        Data["Data/Codon Analysis Module"]:::domain
    end

    subgraph "Utilities Layer"
        CoreUtils["Core Utilities"]:::utility
        ProteinAI["Protein & AI Utilities"]:::utility
    end

    subgraph "Infrastructure Layer"
        Lib["Libraries"]:::infrastructure
        BuildCI["Build & CI/CD"]:::infrastructure
        Installer["Installer Scripts"]:::infrastructure
    end

    %% Data Flow Connections
    Web -->|"AnalyzeDnaRequest"| Adapter
    GUI -->|"UserInteraction"| Adapter
    CLI -->|"CommandInput"| Adapter

    Adapter -->|"InvokeUseCase"| Port
    API -->|"ProcessAPIRequest"| Port

    Port -->|"ExecuteAnalysis"| Core
    Core -->|"UseReadingFrame"| RF
    Core -->|"UseCodonAnalysis"| Data
    Core -->|"UtilizeCoreUtils"| CoreUtils
    Core -->|"UtilizeProteinAI"| ProteinAI

    CoreUtils -->|"SupportOperations"| Core
    ProteinAI -->|"SupportOperations"| Core

    Lib -.->|"Libraries"| Core
    BuildCI -.->|"BuildDeploy"| Core
    Installer -.->|"InstallSupport"| Core

    %% Click Events for Mapped Components
    click Web "https://github.com/verisimilitudex/dnanalyzer/tree/main/web/"
    click GUI "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/ui/gui"
    click CLI "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/ui/cli"
    click Adapter "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/adapter"
    click API "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/api"
    click Core "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/core"
    click Port "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/core/port/in"
    click RF "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/core/readingframe"
    click Data "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/data"
    click CoreUtils "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/utils/core"
    click ProteinAI "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/utils/protein"
    click ProteinAI "https://github.com/verisimilitudex/dnanalyzer/tree/main/src/main/java/DNAnalyzer/utils/ai"
    click Lib "https://github.com/verisimilitudex/dnanalyzer/tree/main/lib/"
    click BuildCI "https://github.com/verisimilitudex/dnanalyzer/blob/main/build.gradle"
    click Installer "https://github.com/verisimilitudex/dnanalyzer/tree/main/installer/"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef adapter fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef domain fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
