# live-image-tracking-tools/napari-geff architecture

> Architecture diagram of the GitHub repository live-image-tracking-tools/napari-geff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/live-image-tracking-tools/napari-geff
- Repository: https://github.com/live-image-tracking-tools/napari-geff

## Overview

##### Project Type and Purpose
- napari-geff is an open-source plugin for the napari visualization platform.
- It provides reader and writer functionality for the Graph Exchange File Format (GEFF), allowing users to drag a GEFF file (zarr store) into napari and view it as a Tracks layer, along with any associated image or label data.

##### File Structure Analysis
- Top-level metadata and CI/CD:
- `.github/` contains issue and PR templates, Dependabot config, and a GitHub Actions workflow for testing and deployment.
- `tox.ini`, `pyproject.toml`, `.pre-commit-config.yaml` configure testing (pytest via tox), package metadata, formatting and linting.
- Examples:
- `examples/graph_labels_seg.zarr/` holds a sample GEFF zarr store with nested groups for image, labels, tracks/nodes/edges, node properties, etc.
- Source code:
- `src/napari_geff/napari.yaml`: plugin registration file (entry points for napari).
- `_reader.py`: implements `Reader` hook for loading GEFF files into napari.
- `_writer.py`: implements `Writer` hook for exporting napari Tracks layers back to GEFF format.
- `utils.py`: shared helper functions (parsing zarr, mapping properties to napari metadata).
- `_tests/`: pytest tests for reader and writer, ensuring correct behavior.
- Packaging:
- `MANIFEST.in`, `LICENSE`, `README.md` for distribution; published on PyPI.

##### Key Insights from README
- Plugin hooks into napari’s I/O system: drag-and-drop or `viewer.open(path, plugin='napari-geff')`.
- Loads directed graphs as Tracks layers, stores node properties as layer features, edge properties in metadata.
- Supports related image/label data per GEFF spec, loaded alongside Tracks.
- Written as a Python package following the napari-plugin-template structure.

##### Main Components
- Napari Core Application (external system)
- napari-geff Plugin System:
- Plugin Registration (napari.yaml)
- Reader Component (`_reader.py`)
- Writer Component (`_writer.py`)
- Utility Module (`utils.py`)
- GEFF Data Store (zarr directory on disk or remote)
- napari Data Structures:
- Tracks Layer
- Image/Labels Layers
- Tests & CI/CD (pytest via tox, GitHub Actions)

##### Relationships and Interactions
- User Action → Napari Core → Plugin Discovery (reads `napari.yaml`)
- Napari Core → invokes Reader on a GEFF path → Reader loads zarr store (via utils), constructs Tracks layer + optional image/labels layers → returns layers to Napari
- User edits or creates Tracks layer → Napari Core → invokes Writer → Writer extracts data from the Tracks layer (and metadata) → writes out GEFF-compliant zarr store on disk
- Tests drive Reader and Writer in isolation via pytest, verified in CI workflow.

##### Architectural Patterns and Principles
- Plugin-based architecture: decoupling core application from I/O implementations.
- Single Responsibility: Reader handles only loading, Writer only exporting, Utils for shared logic.
- Declarative registration: napari.yaml declares entry points without code changes in core.
- Test-driven development with clear test folder structure mirroring implementation modules.

##### Technologies and Frameworks
- Python packaging: pyproject.toml, setuptools
- napari plugin engine (npe2)
- zarr library (for GEFF zarr groups)
- pytest, tox for testing
- GitHub Actions for CI/CD
- pre-commit for code quality

##### Essential Elements to Capture
- Plugin registration and discovery mechanism
- Separation of Reader, Writer, Utils
- GEFF zarr store structure as the canonical external format
- napari data layer types (Tracks, Images, Labels)
- CI/CD pipeline as a supporting process ensuring code quality

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Application
    NC["Napari Core Application"]:::napariCore

    %% Plugin Components
    subgraph "napari-geff Plugin" 
        direction TB
        Reg["Plugin Registration\n(napari.yaml)"]:::plugin
        Reader["Reader Component\n(_reader.py)"]:::plugin
        Writer["Writer Component\n(_writer.py)"]:::plugin
        Utils["Utility Module\n(utils.py)"]:::plugin
    end

    %% Data Store
    DS["GEFF Zarr Store\n(examples)"]:::datastore

    %% Napari Layers
    subgraph "Napari Data Structures"
        direction TB
        TL["Tracks Layer"]:::layer
        IL["Image/Labels Layers"]:::layer
    end

    %% Tests & CI/CD
    subgraph "Testing & CI/CD" 
        direction TB
        TestsDir["Tests Directory\n(_tests/)"]:::support
        TestReader["test_reader.py"]:::support
        TestWriter["test_writer.py"]:::support
        Conft["conftest.py"]:::support
        CI["GitHub Actions Workflow\n(test_and_deploy.yml)"]:::support
        Linting["Pre-commit Config\n(.pre-commit-config.yaml)"]:::support
        Tox["tox.ini"]:::support
        Packaging["Packaging Metadata\n(pyproject.toml,\nMANIFEST.in,\nLICENSE,\nREADME.md)"]:::support
        IssuePR["Issue & PR Templates\n(.github/ISSUE_TEMPLATE/,\nPULL_REQUEST_TEMPLATE.md)"]:::support
        Dependabot["dependabot.yml"]:::support
    end

    %% Runtime Flow
    NC -->|"discover plugin"| Reg
    NC -->|"invoke_read()"| Reader
    Reader -->|"load_zarr()"| DS
    Reader -->|"create Tracks layer"| TL
    Reader -->|"create Image/Labels layers"| IL
    TL -->|return layers| NC

    NC -->|"invoke_write()"| Writer
    Writer -->|"extract layer data"| TL
    Writer -->|"write_geff()"| DS

    %% Utilities usage
    Reader -->|"use utilities"| Utils
    Writer -->|"use utilities"| Utils

    %% Testing & CI/CD Relations
    TestsDir --> TestReader
    TestsDir --> TestWriter
    TestsDir --> Conft
    TestReader -->|"tests Reader"| Reader
    TestWriter -->|"tests Writer"| Writer
    CI --> TestsDir
    CI --> Linting
    CI --> Tox
    CI --> Packaging

    %% Click Events
    click Reg "https://github.com/live-image-tracking-tools/napari-geff/blob/main/src/napari_geff/napari.yaml"
    click Reader "https://github.com/live-image-tracking-tools/napari-geff/blob/main/src/napari_geff/_reader.py"
    click Writer "https://github.com/live-image-tracking-tools/napari-geff/blob/main/src/napari_geff/_writer.py"
    click Utils "https://github.com/live-image-tracking-tools/napari-geff/blob/main/src/napari_geff/utils.py"
    click TestsDir "https://github.com/live-image-tracking-tools/napari-geff/tree/main/src/napari_geff/_tests/"
    click TestReader "https://github.com/live-image-tracking-tools/napari-geff/blob/main/src/napari_geff/_tests/test_reader.py"
    click TestWriter "https://github.com/live-image-tracking-tools/napari-geff/blob/main/src/napari_geff/_tests/test_writer.py"
    click Conft "https://github.com/live-image-tracking-tools/napari-geff/blob/main/src/napari_geff/_tests/conftest.py"
    click DS "https://github.com/live-image-tracking-tools/napari-geff/tree/main/examples/graph_labels_seg.zarr/"
    click CI "https://github.com/live-image-tracking-tools/napari-geff/blob/main/.github/workflows/test_and_deploy.yml"
    click Linting "https://github.com/live-image-tracking-tools/napari-geff/blob/main/.pre-commit-config.yaml"
    click Tox "https://github.com/live-image-tracking-tools/napari-geff/blob/main/tox.ini"
    click Packaging "https://github.com/live-image-tracking-tools/napari-geff/blob/main/pyproject.toml"
    click Packaging "https://github.com/live-image-tracking-tools/napari-geff/blob/main/MANIFEST.in"
    click Packaging "https://github.com/live-image-tracking-tools/napari-geff/tree/main/LICENSE"
    click Packaging "https://github.com/live-image-tracking-tools/napari-geff/blob/main/README.md"
    click IssuePR "https://github.com/live-image-tracking-tools/napari-geff/tree/main/.github/ISSUE_TEMPLATE/"
    click IssuePR "https://github.com/live-image-tracking-tools/napari-geff/blob/main/.github/PULL_REQUEST_TEMPLATE.md"
    click Dependabot "https://github.com/live-image-tracking-tools/napari-geff/blob/main/.github/dependabot.yml"

    %% Styles
    classDef napariCore fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef plugin fill:#90EE90,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#000,stroke-width:1px
    classDef layer fill:#FFD700,stroke:#000,stroke-width:1px
    classDef support fill:#D3D3D3,stroke:#000,stroke-width:1px
```
