# openchemistry/avogadrolibs architecture

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

- Interactive diagram: https://gitdiagram.com/openchemistry/avogadrolibs
- Repository: https://github.com/openchemistry/avogadrolibs

## Overview

##### Project Type and Purpose
- Avogadro 2 is an open-source C++ library collection and desktop application framework for molecular editing, modeling, and visualization.
- It provides core chemistry data structures, I/O for many file formats, a high-performance rendering engine (OpenGL and VTK backends), a plugin architecture, a Qt-based GUI, command-line tools, and Python bindings.
- Use cases include interactive molecule editing, scriptable workflows via Python, batch processing via CLI, and remote job submission via MoleQueue.

##### High-Level Component Analysis from the File Tree
- Top-level directories:
- avogadro: C++ libraries subdivided into calc (energy/force calculations), core (data model), io (file formats), rendering (OpenGL/GLSL), qtgui (Qt widgets/controllers), qtopengl (Qt + OpenGL integration), vtk (VTK rendering), quantumio (quantum chemistry I/O), molequeue (JSON-RPC client), command (CLI tools), qtplugins (GUI plugins).
- python: Python bindings and C++ extension sources.
- scripts: build, packaging, message-extraction, CI helpers.
- tests: unit tests organized by module.
- thirdparty: bundled external libraries.
- utilities: standalone helper executables.
- cmake: build configuration.
- Key patterns:
- Layered architecture: Core → IO → Rendering → GUI → Plugins/Applications
- Plugin framework: plugin manager loads dynamic qtplugins at runtime.
- Factory/Manager patterns: FileFormatManager, PluginFactory.
- Visitor pattern in rendering (scene graph visitors).

##### Insights from README
- Emphasis on cross-platform (Linux, macOS, Windows), modularity, performance, extensibility via plugins and Python.
- Two repos: avogadrolibs (this code) and avogadroapp (application).
- Build system: CMake, CI workflows.

A. Core Library (green)
- Data model: Molecule, Atom, Bond, CoordinateSet, SpaceGroup, etc.
- Utilities: graph algorithms, geometry, unit cell, serializers.
B. IO Library (orange)
- FileFormatManager
- Format implementations: PDB, XYZ, CML, HDF5, quantum formats.
C. Rendering Engine (purple)
- OpenGL backend: rendering/ modules and shaders (.glsl)
- VTK backend: avogadro/vtk wrapper classes.
- Scene graph: Node, Drawable, Visitor.
D. GUI Layer (blue)
- Qt core: qtgui widgets, dialogs, models (MVC).
- QOpenGL integration: qtopengl/glwidget.
- Plugin host: pluginmanager, pluginfactory.
E. Plugins (yellow)
- qtplugins/: many domain-specific tools (force field, symmetry, spectra, etc.).
- Each plugin implements an extension interface and registers GUI menu/tool entries.
F. Application & Tools (teal)
- CLI: avobabel, cjsontocml, qube under avogadro/command.
- Utilities: standalone executables under utilities/.
G. Python Bindings (light green)
- python/avogadro: wrappers for core, io, connect (PyBind11 or custom API).
H. Remote Job Submission (red)
- MoleQueue client: JSON-RPC client module under avogadro/molequeue/client.
- Interacts over network with a MoleQueue server.
I. Build & Test Infrastructure (gray)
- CMake, scripts, tests directory.

- Core → IO (data read/write)
- Core → Rendering (visualization)
- IO → Core (parsing into data model)
- GUI → Core (user commands modify model)
- GUI → Rendering (render current model)
- Plugin host → Plugins (load, register callbacks)
- Plugins ↔ Core/IO/Rendering (plugins make calls to core, io, rendering APIs)
- CLI → Core & IO (batch workflows)
- Python Bindings → Core & IO (scripting)
- MoleQueue client → MoleQueue server (JSON-RPC over HTTP/WebSocket)
- Technologies:
- CMake for build
- Qt 6 for GUI
- OpenGL (GLSL) and VTK for rendering
- JSON, JSON-RPC for MoleQueue
- PyBind11 or custom C++/Python bridging
- Third-party C++ libs (nlohmann/json, pugixml, etc.)
- Patterns:
- Plugin architecture (Factory, dynamic loading)
- MVC in Qt GUI (models, views)
- Scene graph + Visitor in rendering
- Command pattern for CLI operations
- Thread safety via mutex/sharedmutex

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Lower-level Libraries
    subgraph "Core & Libraries"
        direction TB
        Core["Core Library"]:::coreLib
        IO["IO Library"]:::io
        QuantumIO["Quantum Chem I/O"]:::io
        Rendering["Rendering Engine"]:::rendering
        VTK["VTK Rendering Backend"]:::rendering
    end

    %% Mid-level Components
    subgraph "Application Layers"
        direction TB
        GUI["Qt GUI Layer"]:::gui
        QOpenGL["QOpenGL Integration"]:::gui
        PluginFW["Plugin Framework"]:::plugin
        Plugins["GUI Plugins"]:::plugin
        CLI["CLI Tools"]:::tools
        Utils["Utilities"]:::tools
        Python["Python Bindings"]:::python
        MoleQueue["MoleQueue Client"]:::remote
    end

    %% Infrastructure & External
    subgraph "Infrastructure & Dependencies"
        direction TB
        Thirdparty["Third-party Libraries"]:::third
        BuildConfig["Build Config (CMake)"]:::infra
        BuildCI["CI Helpers & Scripts"]:::infra
        Tests["Unit Tests"]:::infra
    end

    %% Interactions
    IO -->|"parses data into"| Core
    Core -->|"provides data model to"| IO
    Core -->|"provides model to"| Rendering
    Core -->|"accessed by"| GUI
    GUI -->|"renders via"| Rendering
    QOpenGL -->|"integrates with"| GUI
    PluginFW -->|"loads"| Plugins
    Plugins -->|"use Core APIs"| Core
    Plugins -->|"use IO APIs"| IO
    Plugins -->|"use Rendering APIs"| Rendering
    CLI -->|"batch workflows on"| Core
    CLI -->|"batch IO operations"| IO
    Python -->|"PyBind interface to"| Core
    Python -->|"PyBind interface to"| IO
    MoleQueue -->|"JSON-RPC over HTTP"| MoleQueue
    Thirdparty -->|"libraries for"| Core
    Thirdparty -->|"libraries for"| Rendering
    BuildConfig -->|"builds"| Core
    BuildConfig -->|"builds"| IO
    BuildConfig -->|"builds"| Rendering
    BuildConfig -->|"builds"| GUI
    BuildCI -->|"scripts for building/testing"| BuildConfig
    Tests -->|"validate"| Core
    Tests -->|"validate"| IO
    Tests -->|"validate"| GUI
    Tests -->|"validate"| QOpenGL
    Tests -->|"validate"| Rendering

    %% Click Events
    click Core "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/core/"
    click IO "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/io/"
    click QuantumIO "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/quantumio/"
    click Rendering "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/rendering/"
    click VTK "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/vtk/"
    click GUI "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/qtgui/"
    click QOpenGL "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/qtopengl/"
    click PluginFW "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/qtplugins/"
    click Plugins "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/qtplugins/"
    click CLI "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/command/"
    click Utils "https://github.com/openchemistry/avogadrolibs/tree/master/utilities/"
    click Python "https://github.com/openchemistry/avogadrolibs/tree/master/python/"
    click MoleQueue "https://github.com/openchemistry/avogadrolibs/tree/master/avogadro/molequeue/"
    click BuildConfig "https://github.com/openchemistry/avogadrolibs/tree/master/cmake/"
    click BuildCI "https://github.com/openchemistry/avogadrolibs/tree/master/scripts/"
    click Tests "https://github.com/openchemistry/avogadrolibs/tree/master/tests/"

    %% Styles
    classDef coreLib fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef io fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef rendering fill:#e0b3ff,stroke:#333,stroke-width:1px
    classDef gui fill:#99ccff,stroke:#333,stroke-width:1px
    classDef plugin fill:#ffff99,stroke:#333,stroke-width:1px
    classDef tools fill:#66cccc,stroke:#333,stroke-width:1px
    classDef python fill:#c6efce,stroke:#333,stroke-width:1px
    classDef remote fill:#ff9999,stroke:#333,stroke-width:1px
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef third fill:#e6e6e6,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
