# noefp/easy_gdb architecture

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

- Interactive diagram: https://gitdiagram.com/noefp/easy_gdb
- Repository: https://github.com/noefp/easy_gdb

## Overview

##### Main Components
- Client Interface: Represent the web browsers (Chrome, Firefox, etc.) that users interact with via HTML/CSS/JS. Note that the UI is built using PHP-generated HTML pages, and the frontend includes assets such as CSS (Bootstrap and custom stylesheets), JavaScript libraries (DataTables, blast_canvas_graph.js, etc.), and image assets.
- Web Server / Application Server: Show the Apache/PHP-based server that processes requests. In the Docker scenario, include the container (“easy_gdb”) containing the PHP code and static assets. Indicate that there is an “install” component with scripts (e.g., setup.sh, Dockerfile, docker-compose.yml) used for provisioning the system.
- Business Logic Layer: Illustrate the core PHP application. This includes numerous entry points (e.g., index.php, gene.php, species_view.php) and helper libraries (such as the “tools” folder with BLAST, expression, lookup, and annotation extraction scripts) that implement the various genomic data functions.
- Data Layer:
- File System: Emphasize that many data types are stored on the file system. There are annotation files, sequence datasets (in folders like “annotations”, “downloads”, “expression_data”), JSON configuration files for customization, and templates providing example data for tool integration.
- External Tools / Services: Include components such as:
- BLAST – executed via scripts located in the “tools/blast” folder along with corresponding BLAST databases.
- JBrowse – the genome browser, which is integrated by loading JBrowse configuration and data (from “jbrowse” folders and example data files).
- Gene Expression and Enrichment – integration with external services like g:Profiler (configured via JSON files in “json_files/tools/enrichment.json”) and using client-side visualization (with expression-specific JavaScript/CSS and optional cartoon images).
- Integration/Customization Configuration: Highlight that the system’s behavior can be heavily customized via configuration files (e.g., easyGDB_conf.php in the “egdb_files/egdb_conf” directory, configuration_path.php, and various JSON files).

##### Relationships and Data Flow
- The client (web browser) sends HTTP requests to the web server.
- The web server (Apache/PHP) routes these requests to various PHP entry scripts (like index.php, help pages, BLAST input pages, gene views, etc.).
- The Application Layer processes requests (for example, performing a BLAST search, fetching annotations, extracting sequences, or rendering a JBrowse genome view); it interacts with files stored on the local file system and optionally queries the PostgreSQL database.
- Outputs are built up from PHP templates and sent back to the client.
- When needed, the application calls external services (for example, linking to g:Profiler or UniProt) or invokes external executables (like BLAST commands and JBrowse’s data preparation scripts).
- In a Docker deployment, incorporate the container orchestration aspect (docker-compose managing at least one container for “easy_gdb”, another for “DB”, etc.).

##### Architectural Patterns and Key Technologies
- Although not a full MVC framework, the project’s structure suggestively separates presentation (templates, JS, CSS, HTML), business logic (PHP functions, tool modules), and data management (file storage and an optional relational database).
- The system leverages web technologies (PHP, CSS, JavaScript) and configuration-driven design (many JSON and PHP configuration files to drive customization).
- Docker is used to containerize the application, so include a container boundary indicating production vs. development deployment.
- Integration with external bioinformatics tools (BLAST, JBrowse, g:Profiler) is a central design principle.

- Component names and clear labels for:
- Web Client
- Apache/PHP Application (including Docker container if applicable)
- Application Modules for BLAST, Genome Browser, Annotation Search, Gene Expression, Lookup, etc.
- File Storage with structured directories (annotations, downloads, expression_data, templates, etc.)
- Optional PostgreSQL Database (and its role for gene annotations)
- External service integration (links to g:Profiler, UniProt, JBrowse external links)
- Grouping related modules together for clarity (e.g., “Genomics Tools” block containing gene lookup, BLAST, annotation extraction, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Interface
    subgraph "Client Interface"
        cClient("Web Browser"):::client
        css1("CSS: easy_gdb.css"):::client
        css2("CSS: datatables.css"):::client
        js1("JS: blast_canvas_graph.js"):::client
        js2("JS: datatable.js"):::client
        tpl1("Template: header.php"):::client
        tpl2("Template: footer.php"):::client
        tpl3("Template: jb_frame.php"):::client
        tpl4("Template: jb_frame_file.php"):::client
    end

    %% Web Server / Application Server
    subgraph "Web Server / Application Server"
        ws("Apache/PHP Server"):::web
        docker("Container: easy_gdb"):::docker
        ep1("Entry: index.php"):::web
        ep2("Entry: gene.php"):::web
        ep3("Entry: species_view.php"):::web
        inst("Install Scripts"):::web
        inst1("Dockerfile"):::web
        inst2("docker-compose.yml"):::web
        inst3("setup.sh"):::web
        inst4("easy_gdb_apache.conf"):::web
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        bl1("Core PHP: index.php"):::logic
        bl2("Core PHP: gene.php"):::logic
        bl3("Core PHP: species.php"):::logic
        bl4("Custom View: custom_view.php"):::logic
        tools("Tool Modules"):::logic
        toolsBlast("tools/blast"):::logic
        toolsExp("tools/expression"):::logic
        toolsLookup("tools/lookup"):::logic
        scripts("Utility Scripts"):::logic
        script1("ImportModule.pm"):::logic
        script2("import_genes.pl"):::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        fs("File System"):::data
        fs1("Annotations: templates/annotations"):::data
        fs2("Downloads: templates/downloads"):::data
        fs3("Expression Data: templates/expression_data"):::data
        fs4("JBrowse Data: templates/jbrowse_example_data"):::data
        fs5("Lookup: templates/lookup"):::data
        fs6("Config Path: templates/configuration_path.php"):::data
        db("PostgreSQL DB"):::data
        dbAccess("DB Access: database_access.php"):::data
    end

    %% External Tools / Services
    subgraph "External Tools/Services"
        extBlast("BLAST Service"):::external
        extBlastDB("BLAST DB: templates/blast_dbs"):::external
        extJBrowse("JBrowse Browser"):::external
        extEnrich("Gene Expression/Enrichment"):::external
        extEnrichConfig("Enrichment Config: templates/egdb_files/json_files/tools/enrichment.json"):::external
        extProf("g:Profiler/UniProt"):::external
    end

    %% Integration / Customization
    subgraph "Integration/Customization"
        confPHP("PHP Config"):::config
        confPHP_file("easyGDB_conf.php"):::config
        confJSON("Customization JSON"):::config
        confJSONDir("Customization Dir: templates/egdb_files/json_files/customization"):::config
        customText("Custom Text"):::config
        customTextDir("egdb_custom_text"):::config
    end

    %% Connections
    cClient -->|"HTTPrequest"| ws
    ws --> ep1
    ws --> ep2
    ws --> ep3
    ws --> inst
    inst --> inst1
    inst --> inst2
    inst --> inst3
    inst --> inst4
    docker --- ws

    %% Routing from Web Server to Business Logic
    ep1 --> bl1
    ep2 --> bl2
    ep3 --> bl3

    %% Business Logic interactions with Data Layer
    bl1 -->|"Reads Config"| fs6
    bl1 --> fs1
    bl1 --> fs2
    bl1 --> fs3
    bl1 --> fs4
    bl2 -->|"DB Query"| dbAccess
    dbAccess --> db

    %% Business Logic Tool Modules interactions
    tools --> toolsBlast
    tools --> toolsExp
    tools --> toolsLookup
    toolsBlast -->|"BLAST_search"| extBlast
    extBlast -->|"Uses"| extBlastDB
    toolsExp -->|"Expression_analysis"| extEnrich
    extEnrich --> extEnrichConfig
    toolsLookup -->|"Lookup_data"| fs5

    %% Utility Scripts
    scripts --> script1
    scripts --> script2

    %% Integration/Customization influence
    confPHP_file --> bl1
    confJSONDir --> bl1
    customTextDir --> bl1

    %% External Tools additional integration
    extEnrich --> extProf

    %% Response flow back to Client
    bl1 -->|"HTML response"| cClient
    bl2 --> cClient
    bl3 --> cClient
    bl4 --> cClient

    %% Styling classes
    classDef client fill:#ccf,stroke:#000,stroke-width:2px;
    classDef web fill:#cfc,stroke:#000,stroke-width:2px;
    classDef docker fill:#eef,stroke:#000,stroke-width:2px;
    classDef logic fill:#fcf,stroke:#000,stroke-width:2px;
    classDef data fill:#ffc,stroke:#000,stroke-width:2px;
    classDef external fill:#cff,stroke:#000,stroke-width:2px;
    classDef config fill:#fdd,stroke:#000,stroke-width:2px;

click css1 "https://github.com/noefp/easy_gdb/blob/main/css/easy_gdb.css"
click css2 "https://github.com/noefp/easy_gdb/blob/main/css/datatables.css"
click js1 "https://github.com/noefp/easy_gdb/blob/main/js/blast_canvas_graph.js"
click js2 "https://github.com/noefp/easy_gdb/blob/main/js/datatable.js"
click tpl1 "https://github.com/noefp/easy_gdb/blob/main/header.php"
click tpl2 "https://github.com/noefp/easy_gdb/blob/main/footer.php"
click tpl3 "https://github.com/noefp/easy_gdb/blob/main/jb_frame.php"
click tpl4 "https://github.com/noefp/easy_gdb/blob/main/jb_frame_file.php"
click ep1 "https://github.com/noefp/easy_gdb/blob/main/index.php"
click ep2 "https://github.com/noefp/easy_gdb/blob/main/gene.php"
click ep3 "https://github.com/noefp/easy_gdb/blob/main/species_view.php"
click inst1 "https://github.com/noefp/easy_gdb/tree/main/install/Dockerfile"
click inst2 "https://github.com/noefp/easy_gdb/blob/main/install/docker-compose.yml"
click inst3 "https://github.com/noefp/easy_gdb/blob/main/install/setup.sh"
click inst4 "https://github.com/noefp/easy_gdb/blob/main/install/easy_gdb_apache.conf"
click tools "https://github.com/noefp/easy_gdb/tree/main/tools"
click toolsBlast "https://github.com/noefp/easy_gdb/tree/main/tools/blast"
click toolsExp "https://github.com/noefp/easy_gdb/tree/main/tools/expression"
click toolsLookup "https://github.com/noefp/easy_gdb/tree/main/tools/lookup"
click script1 "https://github.com/noefp/easy_gdb/blob/main/scripts/ImportModule.pm"
click script2 "https://github.com/noefp/easy_gdb/blob/main/scripts/import_genes.pl"
click fs1 "https://github.com/noefp/easy_gdb/tree/main/templates/annotations"
click fs2 "https://github.com/noefp/easy_gdb/tree/main/templates/downloads"
click fs3 "https://github.com/noefp/easy_gdb/tree/main/templates/expression_data"
click fs4 "https://github.com/noefp/easy_gdb/tree/main/templates/jbrowse_example_data"
click fs5 "https://github.com/noefp/easy_gdb/tree/main/templates/lookup"
click fs6 "https://github.com/noefp/easy_gdb/blob/main/templates/configuration_path.php"
click dbAccess "https://github.com/noefp/easy_gdb/blob/main/templates/egdb_files/egdb_conf/database_access.php"
click extBlastDB "https://github.com/noefp/easy_gdb/tree/main/templates/blast_dbs"
click extEnrichConfig "https://github.com/noefp/easy_gdb/blob/main/templates/egdb_files/json_files/tools/enrichment.json"
click confPHP_file "https://github.com/noefp/easy_gdb/blob/main/templates/egdb_files/egdb_conf/easyGDB_conf.php"
click confJSONDir "https://github.com/noefp/easy_gdb/tree/main/templates/egdb_files/json_files/customization"
click customTextDir "https://github.com/noefp/easy_gdb/tree/main/templates/egdb_files/egdb_custom_text"
```
