# lmmentel/mendeleev architecture

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

- Interactive diagram: https://gitdiagram.com/lmmentel/mendeleev
- Repository: https://github.com/lmmentel/mendeleev

## Overview

##### Main Components
- Core API Library: Represent the “mendeleev” package’s main modules. This node should include the “mendeleev” folder with submodules such as:
- Core logic (e.g., mendeleev/__init__.py, mendeleev/mendeleev.py)
- Data access (e.g., mendeleev/db.py and mendeleev/fetch.py)
- Special utilities (mendeleev/utils.py)
- Element-specific, ion, and isotope functionality (mendeleev/ion.py and mendeleev/models.py)
- Visualization Layer: Emphasize the “vis” submodule (mendeleev/vis/*) that provides visualization functions using Bokeh, Plotly, and Seaborn. This component connects with the core API to render periodic table visualizations.
- Interfaces to External Data: Include separate components representing external interfaces (located in mendeleev/interfaces/) such as NIST ASD and Wikipedia oxidation states. This shows how the system interacts with external data sources.
- Database & Data Migrations: Represent the database component. Include the Alembic migration system (alembic folder along with the alembic.ini configuration) and a reference to the “elements.db” file if applicable. This illustrates how the project manages schema evolution and persists data.
- Command Line Interface (CLI): Include the CLI module (mendeleev/cli.py and the related tests) which serves as an entry point to consume the core functionalities directly from the terminal.
- Interactive Web Application: Even if not part of the codebase per se, the README describes an interactive web app (deployed, for example, on Heroku) that serves as a frontend for exploring the data. Include this as an external consumer of the API.

##### Relationships and Data Flow
- The Core API should be shown interacting with the Database and managing data migrations (using Alembic).
- The external interfaces (NIST_ASD, wiki oxidation states) feed data into the core system.
- Visualizations receive processed data from the API and pass on rendered content to end-users (or the web app front end).

##### Architectural Patterns and Design Principles
- Modular Architecture: Separate modules for data retrieval, data modeling, and visualization.
- Layered Design: Distinct layers for data (database), business logic (core API and models), presentation (CLI, web app, and visualization modules), and external integrations (interfaces).
- Emphasis on Extensibility: Extensible interfaces for additional data sources (as evidenced by the “interfaces” subdirectory), which allows the system to grow.
- Testing and Documentation: Robust tests and detailed documentation indicate a commitment to maintainability and reliability.

##### Technologies, Frameworks, and Libraries
- Pandas: Integration for data manipulation is mentioned.
- Bokeh, Plotly, Seaborn: As visualization libraries.
- Alembic: For database migrations with a possible backend database (likely SQLite or another RDBMS).
- Command line scripts using standard Python CLI techniques.
- External Data Interfaces might rely on HTTP libraries or other parsing utilities.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Core API Library Subgraph
    subgraph "Core API Library"
        INIT["Init (__init__.py)"]:::core
        CORE["Core (mendeleev.py)"]:::core
        CORE_DB["DB (db.py)"]:::core
        FETCH["Fetch (fetch.py)"]:::core
        UTILS["Utils (utils.py)"]:::core
        ION["Ion (ion.py)"]:::core
        MODELS["Models (models.py)"]:::core
        ECONF["Econf (econf.py)"]:::core
        ELEC["Electronegativity (electronegativity.py)"]:::core
    end

    %% Visualization Layer Subgraph
    subgraph "Visualization Layer"
        BOKEH["Bokeh (bokeh.py)"]:::vis
        PLOTLY["Plotly (plotly.py)"]:::vis
        SEABORN["Seaborn (seaborn.py)"]:::vis
        PERIODIC["Periodic Table (periodictable.py)"]:::vis
        VISUTILS["Vis Utils (utils.py)"]:::vis
    end

    %% External Interfaces Subgraph
    subgraph "External Interfaces"
        NIST["NIST ASD (nist_asd.py)"]:::interface
        WIKI["Wiki Oxidation (wiki_oxidation_states.py)"]:::interface
    end

    %% Database & Migrations Subgraph
    subgraph "Database & Migrations"
        DATABASE["(( Database ))"]:::db
        ALEMBIC["Alembic (alembic/)"]:::db
        ALEMBICCFG["Alembic Config (alembic.ini)"]:::db
    end

    %% Other Components
    CLI["CLI (cli.py)"]:::cli
    DOCS["Docs (docs/)"]:::docs
    TESTS["Tests (tests/)"]:::docs
    WEB["Interactive Web App"]:::web

    %% Relationships
    CLI -->|"data_request"| CORE
    WEB -->|"api_access"| CORE
    NIST -->|"feed_data"| CORE
    WIKI -->|"feed_data"| CORE
    CORE -->|"persist_data"| DATABASE
    CORE -->|"migration_scripts"| ALEMBIC
    CORE -->|"visual_data"| PERIODIC
    DOCS ---|"documentation"| CORE
    TESTS ---|"testing"| CORE

    %% Class Definitions for styling with colors
    classDef core fill:#9fdfbf,stroke:#333,stroke-width:2px;
    classDef vis fill:#bde0fe,stroke:#333,stroke-width:2px;
    classDef interface fill:#ffcfdf,stroke:#333,stroke-width:2px;
    classDef db fill:#fce38a,stroke:#333,stroke-width:2px;
    classDef cli fill:#ffdf91,stroke:#333,stroke-width:2px;
    classDef docs fill:#d3c0eb,stroke:#333,stroke-width:2px;
    classDef web fill:#caffbf,stroke:#333,stroke-width:2px;

    %% Click Events for Core API Library
    click INIT "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/__init__.py"
    click CORE "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/mendeleev.py"
    click CORE_DB "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/db.py"
    click FETCH "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/fetch.py"
    click UTILS "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/utils.py"
    click ION "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/ion.py"
    click MODELS "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/models.py"
    click ECONF "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/econf.py"
    click ELEC "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/electronegativity.py"

    %% Click Events for Visualization Layer
    click BOKEH "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/vis/bokeh.py"
    click PLOTLY "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/vis/plotly.py"
    click SEABORN "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/vis/seaborn.py"
    click PERIODIC "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/vis/periodictable.py"
    click VISUTILS "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/vis/utils.py"

    %% Click Events for External Interfaces
    click NIST "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/interfaces/nist_asd.py"
    click WIKI "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/interfaces/wiki_oxidation_states.py"

    %% Click Events for Database & Migrations
    click DATABASE "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/elements.db"
    click ALEMBIC "https://github.com/lmmentel/mendeleev/tree/master/alembic/"
    click ALEMBICCFG "https://github.com/lmmentel/mendeleev/blob/master/alembic.ini"

    %% Click Event for CLI
    click CLI "https://github.com/lmmentel/mendeleev/blob/master/mendeleev/cli.py"

    %% Click Events for Documentation & Testing
    click DOCS "https://github.com/lmmentel/mendeleev/tree/master/docs/"
    click TESTS "https://github.com/lmmentel/mendeleev/tree/master/tests/"
```
