# exabyte-io/made architecture

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

- Interactive diagram: https://gitdiagram.com/exabyte-io/made
- Repository: https://github.com/exabyte-io/made

## Overview

##### Project type and purpose
- This is an open‐source, multi‐language library (“Made”) for Materials Design (core API and utilities), implemented in JavaScript/TypeScript (for browser/Node.js) and in Python (for desktop/Pyodide).
- It provides:
- Core domain classes (Material, Basis, Lattice, Cell, Constraints)
- File‐format parsers (POSCAR, XYZ, QE, etc.)
- Structural generation & analysis tools (supercell, surfaces, combinatorial sets, etc.)

A. External Data Formats (POSCAR, XYZ, Quantum ESPRESSO…)
B. Parsers Layer (src/js/parsers / src/py/mat3ra/.../parsers)
C. Core Domain Layer
– Basis
– Lattice (& ReciprocalLattice)
– Cell (primitive/conventional)
– Material
– AtomicConstraints
D. Tools Layer (src/js/tools / src/py/mat3ra/.../tools)
– build (defect, grain boundary, slab, nanoparticle, etc.)
– analyze (coordination, RDF, etc.)
– calculate (ASE, interaction functions)
– convert, modify, optimize, site, third_party
E. Packaging & Build
– JS/TS: tsconfig → Babel/TypeScript → dist/js + .d.ts → npm
– Python: pyproject.toml → wheel → PyPI (optionally with [tools])
– CI/CD: GitHub Actions (cicd.yml)
– Pre‐commit hooks (Husky + ESLint + Prettier / lint‐staged)
F. Test Suites
– JS: Mocha tests under tests/js
– Python: pytest under tests/py

##### Component relationships and data flow
- External Data Formats → Parsers → Domain Objects
- Domain Objects ↔ Tools (tools consume and sometimes return new domain objects)
- Domain Objects & Tools → exported API surface (index.ts / __init__.py)
- Source → Build/Transpile → Distribution packages → Registry (npm / PyPI)
- All code & tests → CI/CD pipeline → Automated testing & publishing

##### Architectural patterns & design principles
- Layered architecture: Parsers → Core domain → Tools → API export
- Modular design: each concept (basis, cell, lattice) in its own module/directory
- Language‐agnostic convention: mirrored folder structure in JS (src/js/…) and Python (src/py/mat3ra/…)
- Clear separation of pure class methods vs. external‐parameter tools (per ESSE & in‐README conventions)

##### Detail level
- Every major module directory as a separate component (e.g., “parsers”, “tools/build”, “tools/analyze”)
- Test frameworks and test directories as a separate “Testing” subsystem connected to source code

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Formats
    EF1["POSCAR"]:::external
    EF2["XYZ"]:::external
    EF3["Quantum ESPRESSO"]:::external

    %% JavaScript/TypeScript Platform
    subgraph "JavaScript/TypeScript" 
        direction TB
        ParsersJS["Parsers"]:::js
        click ParsersJS "https://github.com/exabyte-io/made/tree/main/src/js/parsers"

        subgraph "Core Domain (JS)"
            direction TB
            BasisJS["Basis"]:::js
            click BasisJS "https://github.com/exabyte-io/made/tree/main/src/js/basis"
            LatticeJS["Lattice"]:::js
            click LatticeJS "https://github.com/exabyte-io/made/tree/main/src/js/lattice"
            CellJS["Cell"]:::js
            click CellJS "https://github.com/exabyte-io/made/tree/main/src/js/cell"
            ConstraintsJS["AtomicConstraints"]:::js
            click ConstraintsJS "https://github.com/exabyte-io/made/tree/main/src/js/constraints"
            MaterialJS["Material"]:::js
            click MaterialJS "https://github.com/exabyte-io/made/blob/main/src/js/material.ts"
        end

        ToolsJS["Tools"]:::js
        click ToolsJS "https://github.com/exabyte-io/made/tree/main/src/js/tools"
    end

    %% Python Platform
    subgraph "Python" 
        direction TB
        subgraph "Core Domain (Py)"
            direction TB
            BasisPy["Basis"]:::py
            click BasisPy "https://github.com/exabyte-io/made/tree/main/src/py/mat3ra/made/basis"
            LatticePy["Lattice"]:::py
            click LatticePy "https://github.com/exabyte-io/made/blob/main/src/py/mat3ra/made/lattice.py"
            CellPy["Cell"]:::py
            click CellPy "https://github.com/exabyte-io/made/blob/main/src/py/mat3ra/made/cell.py"
            MaterialPy["Material"]:::py
            click MaterialPy "https://github.com/exabyte-io/made/blob/main/src/py/mat3ra/made/material.py"
        end

        ToolsPy["Tools"]:::py
        click ToolsPy "https://github.com/exabyte-io/made/tree/main/src/py/mat3ra/made/tools"
    end

    %% Source and Packaging & Build
    Source["Source Code"]:::build
    tsconfig["tsconfig.json"]:::build
    click tsconfig "https://github.com/exabyte-io/made/blob/main/tsconfig.json"
    DistJS["dist/js"]:::build
    click DistJS "https://github.com/exabyte-io/made/tree/main/dist/js"
    PyProj["pyproject.toml"]:::build
    click PyProj "https://github.com/exabyte-io/made/blob/main/pyproject.toml"
    CICD["CI/CD Pipeline"]:::build
    click CICD "https://github.com/exabyte-io/made/blob/main/.github/workflows/cicd.yml"
    Hooks["Pre-commit & Linters"]:::build
    click Hooks "https://github.com/exabyte-io/made/blob/main/.husky"
    click Hooks "https://github.com/exabyte-io/made/blob/main/.pre-commit-config.yaml"
    click Hooks "https://github.com/exabyte-io/made/blob/main/.eslintrc.json"
    click Hooks "https://github.com/exabyte-io/made/blob/main/.prettierrc"

    %% Test Suites
    JSTest["JS Tests"]:::test
    click JSTest "https://github.com/exabyte-io/made/tree/main/tests/js"
    PyTest["Py Tests"]:::test
    click PyTest "https://github.com/exabyte-io/made/tree/main/tests/py"

    %% Registries
    Npm["npm Registry"]:::registry
    PyPI["PyPI Registry"]:::registry

    %% Data Flows
    EF1 --> ParsersJS
    EF2 --> ParsersJS
    EF3 --> ParsersJS

    ParsersJS --> BasisJS
    ParsersJS --> LatticeJS
    ParsersJS --> CellJS
    ParsersJS --> ConstraintsJS
    ParsersJS --> MaterialJS

    BasisJS <--> ToolsJS
    LatticeJS <--> ToolsJS
    CellJS <--> ToolsJS
    ConstraintsJS <--> ToolsJS
    MaterialJS <--> ToolsJS

    BasisPy <--> ToolsPy
    LatticePy <--> ToolsPy
    CellPy <--> ToolsPy
    MaterialPy <--> ToolsPy

    Source --> tsconfig
    tsconfig --> DistJS
    DistJS --> Npm

    Source --> PyProj
    PyProj --> PyPI

    Source --> CICD
    Source --> Hooks
    Source --> JSTest
    Source --> PyTest

    %% Styles
    classDef external fill:#ddd,stroke:#999
    classDef js fill:#bbdefb,stroke:#1976d2
    classDef py fill:#c8e6c9,stroke:#388e3c
    classDef build fill:#ffcc80,stroke:#f57c00
    classDef test fill:#ffe082,stroke:#f9a825
    classDef registry fill:#d1c4e9,stroke:#7b1fa2
```
