# mmcguffi/plannotate architecture

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

- Interactive diagram: https://gitdiagram.com/mmcguffi/plannotate
- Repository: https://github.com/mmcguffi/plannotate

## Overview

##### Project type and purpose
- pLannotate is a full-stack bioinformatics application:
- Backend “annotation engine” (Python modules that parse input FASTA/GenBank, run searches, assemble annotation results)
- Two presentation layers:
– Command-Line Interface (CLI) for batch annotation
– Streamlit‐based local web server for interactive use
- Data layer of built-in reference databases (CSV, FASTA, YAML) and HTML templates

##### File structure
- Top‐level:
- plannotate/ — core Python package
- .streamlit/ — Streamlit config
- environment.yml, requirements.txt, setup.py — dependency and packaging
- tests/ — unit and manual tests
- .github/workflows/ — CI pipelines
- plannotate/ submodules:
- .py — core annotation logic (search engines, filtering)
- infernal.py — wrappers around external search tools (e.g., Infernal)
- resources.py — loading and caching of sequence-record utilities
- bokeh_plot.py — transforms annotation results into interactive Bokeh figures
- streamlit_app.py — Streamlit server (UI/controller)
- pLannotate.py — CLI entry points (batch, setupdb, yaml dump)
- data/ — static assets:
– data/data/*.csv, .yml — built-in feature/type databases
– data/fastas/ — reference sequences
– data/templates/ — HTML snippets for web output
- Config & packaging:
- setup.py & environment.yml define installation and conda environment
- tox.ini, .github/workflows drive testing matrix

##### Extract architectural insights from README
- Two usage modes: `plannotate batch` (CLI) and `plannotate streamlit` (web UI)
- Data flow: input sequence → annotation engine → get_seq_record → get_bokeh → HTML/GBK/CSV outputs or live plot
- Customizability: users can supply YAML to point at external databases

##### Main components & interactions
A. Presentation layer
1. CLI Module (pLannotate.py)
2. Streamlit App (streamlit_app.py)
3. Bokeh Plot Renderer (bokeh_plot.py + templates)
B. Core Logic layer
1. Annotation Engine (annotate.py)
2. Search Wrappers (infernal.py, plus any BLAST/HMMER calls)
3. Resource Loader (resources.py)
C. Data layer
1. Built-in Databases (CSV/YAML under data/data/)
2. Reference FASTA sequences (data/fastas/)
3. HTML Templates (data/templates/)
D. Configuration & Infrastructure
1. Conda Environment (environment.yml)
2. Package Metadata (setup.py, requirements.txt)
3. CI/CD (tox.ini, GitHub workflows)
E. External Dependencies
1. Python 3 runtime
2. Streamlit framework
3. Bokeh visualization library
4. BioPython for SeqRecord
5. External search tools (Infernal/HMMER) invoked via infernal.py

##### Relationships & data flows
- User invokes CLI or opens the Streamlit web page
→ CLI/Streamlit processes input sequence
→ Calls Annotation Engine
→ Engine uses Resource Loader to fetch reference databases & templates
→ Engine calls Search Wrappers (infernal.py) to perform sequence searches
→ Collects “hits” and assembles annotation results
→ Passes results to Bokeh Plot Renderer
→ Generates interactive HTML (for web) or standalone HTML/CSV/GBK files (for CLI)
- Configuration (YAML, environment.yml) influences Resource Loader and Search Wrappers

##### Architectural patterns & design principles
- “Separation of Concerns”:
- Clear layering: Presentation (UI) vs. Core Logic vs. Data
- Modular design:
- Each Python module has a single responsibility (annotate, plot, CLI, resources)
- Extensibility:
- Databases defined in YAML; new data sources or search tools can be added without changing core logic
- Reusability:
- Core annotation logic is decoupled from the UI, so it can be imported as a Python module

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::ext

    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Module"]:::ui
        Streamlit["Streamlit App"]:::ui
        BokehRenderer["Bokeh Plot Renderer"]:::ui
    end

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        AnnotationEngine["Annotation Engine"]:::core
        SearchWrappers["Search Wrappers"]:::core
        ResourceLoader["Resource Loader"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        BuiltinDB(("Built-in Databases")):::data
        ReferenceFASTAs(("Reference FASTA Sequences")):::data
        HTMLTemplates[/HTML Templates/]:::data
        Icons[\\Icons\\]:::data
    end

    %% Configuration & Infrastructure
    subgraph "Configuration & Infrastructure"
        CondaEnv[Conda Environment]:::config
        SetupPy[setup.py]:::config
        Requirements[requirements.txt]:::config
        Workflows[CI/CD Workflows]:::config
        Tox[tox.ini]:::config
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Python3[Python 3 Runtime]:::ext
        StreamlitExt[Streamlit Framework]:::ext
        BokehExt[Bokeh Visualization Library]:::ext
        BioPython[BioPython Library]:::ext
        ExtTools[External Search Tools]:::ext
    end

    %% Outputs
    Files[/Output: HTML/CSV/GBK files/]:::ui
    Browser[/Output: Interactive Browser/]:::ui

    %% Relationships
    User -->|uses| CLI
    User -->|opens| Streamlit

    CLI -->|calls| AnnotationEngine
    Streamlit -->|calls| AnnotationEngine

    AnnotationEngine -->|loads| ResourceLoader
    AnnotationEngine -->|executes| SearchWrappers
    AnnotationEngine -->|sends results to| BokehRenderer

    ResourceLoader -->|fetches data from| BuiltinDB
    ResourceLoader -->|fetches data from| ReferenceFASTAs
    ResourceLoader -->|fetches templates from| HTMLTemplates
    ResourceLoader -->|fetches icons from| Icons

    BokehRenderer -->|generates| Files
    BokehRenderer -->|renders in| Browser

    %% Configuration injections
    CondaEnv -.->|configures| ResourceLoader
    CondaEnv -.->|configures| SearchWrappers
    SetupPy -.->|metadata for| AnnotationEngine
    Requirements -.->|dependencies for| AnnotationEngine
    Workflows -.->|CI for| CLI
    Workflows -.->|CI for| Streamlit
    Tox -.->|tests| AnnotationEngine

    %% External dependencies links
    Python3 -->|runtime for| AnnotationEngine
    StreamlitExt -->|provides UI to| Streamlit
    BokehExt -->|provides plots for| BokehRenderer
    BioPython -->|used by| ResourceLoader
    ExtTools -->|invoked by| SearchWrappers

    %% Click Events
    click CLI "https://github.com/mmcguffi/plannotate/blob/master/plannotate/pLannotate.py"
    click Streamlit "https://github.com/mmcguffi/plannotate/blob/master/plannotate/streamlit_app.py"
    click BokehRenderer "https://github.com/mmcguffi/plannotate/blob/master/plannotate/bokeh_plot.py"
    click AnnotationEngine "https://github.com/mmcguffi/plannotate/blob/master/plannotate/annotate.py"
    click SearchWrappers "https://github.com/mmcguffi/plannotate/blob/master/plannotate/infernal.py"
    click ResourceLoader "https://github.com/mmcguffi/plannotate/blob/master/plannotate/resources.py"
    click BuiltinDB "https://github.com/mmcguffi/plannotate/tree/master/plannotate/data/data/"
    click ReferenceFASTAs "https://github.com/mmcguffi/plannotate/tree/master/plannotate/data/fastas/"
    click HTMLTemplates "https://github.com/mmcguffi/plannotate/tree/master/plannotate/data/templates/"
    click Icons "https://github.com/mmcguffi/plannotate/tree/master/plannotate/data/images/"
    click CondaEnv "https://github.com/mmcguffi/plannotate/blob/master/environment.yml"
    click SetupPy "https://github.com/mmcguffi/plannotate/blob/master/setup.py"
    click Requirements "https://github.com/mmcguffi/plannotate/blob/master/requirements.txt"
    click Workflows "https://github.com/mmcguffi/plannotate/tree/master/.github/workflows/"
    click Tox "https://github.com/mmcguffi/plannotate/blob/master/tox.ini"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#21618C,color:#1B4F72
    classDef core fill:#D4EFDF,stroke:#1D8348,color:#145A32
    classDef data fill:#FCF3CF,stroke:#B7950B,color:#7E5109
    classDef config fill:#E8DAEF,stroke:#8E44AD,color:#512E5F
    classDef ext fill:#E5E8E8,stroke:#85929E,color:#566573
```
