# acceleratedscience/openad-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/acceleratedscience/openad-toolkit
- Repository: https://github.com/acceleratedscience/openad-toolkit

## Overview

##### Project Type and Purpose
- OpenAD is an open-source, full-featured molecular & materials research toolkit written in Python.
- It exposes a low-code API/CLI, Jupyter Notebook integration (magic commands), and an optional web-based GUI (Flask + WASM).
- It integrates with external LLM services, RDKit via WebAssembly, and supports plugin/toolkit extensions.

##### High-Level Architecture Analysis
- Layered, modular design with clear separation of concerns:
- User Interfaces (CLI, Jupyter, Web UI)
- Application Orchestration (openad/app, openad/api)
- Core Domain Logic (openad/core, openad/helpers, openad/mmols, openad/smols)
- Service Integrations (openad/llm_assist, openad/openad_model_plugin)
- Static GUI Bundles (openad/gui-build, openad/gui-build-proxy)
- Plugins & Toolkits (openad/plugins, openad/user_toolkits)
- Background Workers (openad/workers/file_system.py)
- External Dependencies (LLM endpoints, RDKit WASM)

##### Main Components
A. User Interface Layer
1. CLI EntryPoint (`openad` console script, openad/openad_api.py)
2. Jupyter Notebook Magic (`openad/app/magic/openad_magic.py`)
3. Web UI Frontend
- Flask Server (openad/app/main.py, openad/flask_apps/routes.py)
- Static Assets & WASM (openad/gui-build, openad/gui-build-proxy, RDKit_minimal.wasm)
B. Application Layer
1. API Handlers (`openad/api.py`)
2. App Orchestrator (`openad/app/*`: login_manager, main_lib, memory, metadata.json)
C. Core Domain Layer
1. Language & Grammar Engines (`openad/core/grammar.py`, lang_*.py)
2. Molecule/Material Commands & Transforms (`openad/mmols`, `openad/smols`)
3. Helpers (file I/O, data formats, credentials)
D. Service Integration Layer
1. LLM Assistant (`openad/llm_assist/*`)
2. Model Plugin Service (`openad/openad_model_plugin/*`)
3. External LLM APIs (OpenAI, Hugging Face, etc.)
E. Extension Layer
1. Built-in Plugins (`openad/plugins/*`)
2. User Toolkits (`openad/user_toolkits/*`)
F. Workers / Background Tasks
- File system operations, long-running jobs (`openad/workers/file_system.py`)

##### Relationships & Data Flows
- CLI & Jupyter → Application Layer → Core Domain → Service Integration → External LLMs / RDKit WASM → return results back up
- Web UI Frontend ↔ Flask Server → Application Layer → Core Domain → Services
- Plugins & Toolkits hook into Application Layer via the openad/api or openad/app plugin registries
- Workers handle asynchronous or heavy tasks on behalf of the Application Layer

##### Architectural Patterns & Principles
- Layered architecture (UI → API/App → Core → Services)
- Plugin/extension architecture (discoverable plugins in openad/plugins and user_toolkits)
- MVC in the Flask component (routes serve static bundle + JSON endpoints)
- Separation of concerns: UI code (JS/WASM) vs. business logic (Python)
- Low-code integration: single python package exposes CLI, API, Jupyter magic

##### Technologies & Frameworks to Annotate
- Python 3.x, Flask (web server), Jupyter/IPython magic
- JavaScript/TypeScript front end, WebAssembly (RDKit)
- HTTP/REST for Web UI ↔ Backend
- LLM integration via HTTP/SDKs (OpenAI, etc.)
- Packaging & build: pyproject.toml, Makefile, setup.sh

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        CLI["CLI EntryPoint"]:::ui
        Jupyter["Jupyter Notebook Magic"]:::ui
        subgraph "Web UI Frontend"
            direction TB
            Flask["Flask Server"]:::ui
            Static["Static Assets & WASM"]:::ui
        end
    end

    %% Application Layer
    subgraph "Application/API Layer"
        direction TB
        API["API Handlers"]:::app
        Orchestrator["App Orchestrator"]:::app
    end

    %% Core Domain Layer
    subgraph "Core Domain Layer"
        direction TB
        Grammar["Language & Grammar Engines"]:::core
        Molecules["Molecule/Material Commands"]:::core
        Helpers["Helpers"]:::core
    end

    %% Service Integration Layer
    subgraph "Service Integration Layer"
        direction TB
        LLMAssist["LLM Assistant"]:::service
        ModelPlugin["Model Plugin Service"]:::service
        ExternalLLM["External LLM APIs"]:::service
        RDKitWASM["RDKit via WASM"]:::service
    end

    %% Extension Layer
    subgraph "Extensions & Plugins"
        direction TB
        BuiltIn["Built-in Plugins"]:::ext
        UserTK["User Toolkits"]:::ext
    end

    %% Workers
    Workers["Background Workers"]:::worker

    %% Data Flows
    CLI -->|uses| API
    Jupyter -->|uses| API
    Flask -->|calls| API
    Static -->|loads| Flask

    API -->|orchestrates| Orchestrator
    Orchestrator -->|invokes| Grammar
    Orchestrator -->|invokes| Molecules
    Orchestrator -->|uses| Helpers

    Grammar -->|calls| LLMAssist
    Molecules -->|calls| RDKitWASM
    LLMAssist -->|integrates| ExternalLLM
    ModelPlugin -->|hooks| API

    API -->|asynchronous| Workers
    Workers -->|callbacks to| API

    BuiltIn -->|registers| API
    UserTK -->|registers| API

    %% Styling
    classDef ui fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef app fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef core fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef service fill:#e1bee7,stroke:#8e24aa,color:#4a148c
    classDef ext fill:#fff9c4,stroke:#fdd835,color:#f57f17
    classDef worker fill:#eeeeee,stroke:#9e9e9e,color:#424242

    %% Click Events
    click CLI "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/openad_api.py"
    click Jupyter "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/app/magic/openad_magic.py"
    click Flask "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/app/main.py"
    click Flask "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/flask_apps/launcher.py"
    click Flask "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/flask_apps/dataviewer/routes.py"
    click Flask "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/flask_apps/example/routes.py"
    click Static "https://github.com/acceleratedscience/openad-toolkit/tree/main/openad/gui-build/"
    click Static "https://github.com/acceleratedscience/openad-toolkit/tree/main/openad/gui-build-proxy/"
    click Static "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/gui-build/rdkit/RDKit_minimal.wasm"
    click Static "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/gui-build-proxy/rdkit/RDKit_minimal.wasm"
    click API "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/api.py"
    click Orchestrator "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/app/main_lib.py"
    click Orchestrator "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/app/login_manager.py"
    click Orchestrator "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/app/memory.py"
    click Orchestrator "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/app/metadata.json"
    click Grammar "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/core/grammar.py"
    click Grammar "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/core/lang_dev.py"
    click Grammar "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/core/lang_file_system.py"
    click Grammar "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/core/lang_runs.py"
    click Grammar "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/core/lang_sessions_and_registry.py"
    click Grammar "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/core/lang_workspaces.py"
    click Molecules "https://github.com/acceleratedscience/openad-toolkit/tree/main/openad/mmols/"
    click Molecules "https://github.com/acceleratedscience/openad-toolkit/tree/main/openad/smols/"
    click Helpers "https://github.com/acceleratedscience/openad-toolkit/tree/main/openad/helpers/"
    click LLMAssist "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/llm_assist/llm_interface.py"
    click LLMAssist "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/llm_assist/prime_chat.py"
    click LLMAssist "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/llm_assist/model_reference.py"
    click ModelPlugin "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/openad_model_plugin/openad_model_toolkit.py"
    click ModelPlugin "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/openad_model_plugin/services.py"
    click ModelPlugin "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/openad_model_plugin/catalog_model_services.py"
    click ModelPlugin "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/openad_model_plugin/auth_services.py"
    click BuiltIn "https://github.com/acceleratedscience/openad-toolkit/tree/main/openad/plugins/edit_json/"
    click BuiltIn "https://github.com/acceleratedscience/openad-toolkit/tree/main/openad/plugins/style_parser/"
    click UserTK "https://github.com/acceleratedscience/openad-toolkit/tree/main/openad/user_toolkits/DS4SD/"
    click UserTK "https://github.com/acceleratedscience/openad-toolkit/tree/main/openad/user_toolkits/RXN/"
    click Workers "https://github.com/acceleratedscience/openad-toolkit/blob/main/openad/workers/file_system.py"
```
