# benchling-open-source/allotropy architecture

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

- Interactive diagram: https://gitdiagram.com/benchling-open-source/allotropy
- Repository: https://github.com/benchling-open-source/allotropy

## Overview

##### Main Components
- Core Library: At the heart of the system is the core module (located in src/allotropy). This includes the central functionality, such as the “to_allotrope” module and “parser_factory,” which are responsible for accepting input files/streams and orchestrating the conversion.
- Parsers: The largest part of the codebase is the collection of vendor-specific parsers found in the src/allotropy/parsers directory. Each parser module (for vendors like Agilent Gen5, Beckman, ThermoFisher, etc.) typically contains:
- A “reader” for reading and initial processing of file formats.
- A “parser” that extracts structured data.
- A “structure” module that organizes the extracted data according to instrument-specific logic.
- Constants used in parsing.
- Calculated Documents and JSON-to-CSV Utilities: Additional functionality (e.g. in src/allotropy/calcdocs and src/allotropy/json_to_csv) supports data aggregation, transformation, and alternative output formats.
- Testing and Infrastructure: The tests directory and scripts folder represent the infrastructure components for continuous integration, linting, and environment setup but are not part of the runtime conversion flow. They help verify correct functionality of all core modules and parsers.

##### Relationships and Data Flow
- Conversion Output: Finally, show a “Conversion Output” node (representing the output JSON ASM dictionary) being produced by the “to_allotrope” functions. This represents the final consumer-ready output.
- Utility and Support Layers: Optionally, include supporting modules such as the “Calculated Documents” for specialized outputs and “JSON-to-CSV” for additional transformation outputs.

##### Architectural Patterns and Design Principles
- Modular and Extensible Architecture: Emphasize that the design uses a factory pattern (via parser_factory) to allow easy extension when new instrument vendors are supported.
- Separation of Concerns: Clearly delineate the responsibilities – reading the raw file, parsing the content, restructuring data, and finally mapping it to a standardized schema.
- Testing and CI: Although not part of the conversion execution flow, note that there is a robust testing ecosystem (unit tests, integration tests) that validates every component and ensures backward compatibility.

##### Detailed Component Breakdown (Optional)
- Within the “Vendor Parsers” block, you might subdivide into its sub-components: e.g., “Reader”, “Parser”, “Structure”, “Constants” – showing that the raw file is processed step-by-step.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Input Data (File/IO)"]:::input
    subgraph "Core Library"
        B["Parser Factory"]:::core
        E["to_allotrope Conversion"]:::core
    end
    subgraph "Vendor Parsers"
        V1["Reader"]:::vendor
        V2["Parser"]:::vendor
        V3["Structure Creator"]:::vendor
    end
    D["Schema Mapper/Schema Parser"]:::schema
    F["Conversion Output (ASM JSON)"]:::output
    subgraph "Utilities"
        G["Calculated Documents"]:::utils
        H["JSON-to-CSV"]:::utils
    end
    I["Testing & CI Infrastructure"]:::test

    A --> B
    B --> V1
    V1 --> V2
    V2 --> V3
    V3 --> D
    D --> E
    E --> F
    E --> G
    E --> H

    %% Click Events
    click B "https://github.com/benchling-open-source/allotropy/blob/main/src/allotropy/parser_factory.py"
    click E "https://github.com/benchling-open-source/allotropy/blob/main/src/allotropy/to_allotrope.py"
    click V3 "https://github.com/benchling-open-source/allotropy/tree/main/src/allotropy/parsers/agilent_gen5/"
    click D "https://github.com/benchling-open-source/allotropy/tree/main/src/allotropy/schema_parser/"
    click G "https://github.com/benchling-open-source/allotropy/tree/main/src/allotropy/calcdocs/"
    click H "https://github.com/benchling-open-source/allotropy/tree/main/src/allotropy/json_to_csv/"
    click I "https://github.com/benchling-open-source/allotropy/tree/main/tests/"

    %% Styles
    classDef input fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef output fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef core fill:#d1c4e9,stroke:#5e35b1,stroke-width:2px;
    classDef vendor fill:#ffe082,stroke:#ff8f00,stroke-width:2px;
    classDef schema fill:#b2dfdb,stroke:#00796b,stroke-width:2px;
    classDef utils fill:#ffcc80,stroke:#f57c00,stroke-width:2px;
    classDef test fill:#eeeeee,stroke:#757575,stroke-width:2px;
```
