# metamolecular/trey architecture

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

- Interactive diagram: https://gitdiagram.com/metamolecular/trey
- Repository: https://github.com/metamolecular/trey

## Overview

##### Project type and purpose
- This is a Rust library/crate (“Trey”) whose sole purpose is to provide primitives for reading and writing V3000 CTfile formats (chemical connection‐table files). It is not a client/server or full-stack app but an open-source toolkit/library for parsing and serializing chemoinformatics file formats.

##### File structure
- Top‐level artifacts:
- Cargo.toml, rustfmt.toml, .cargo/config.toml – Cargo build and formatting configuration
- src/lib.rs – the public API entry point
- src/header/… – modules for parsing and representing the CTfile header block
- src/ctab/… – modules for representing and parsing the connection table (atoms, bonds, R-groups, etc.)
- src/write/… – modules for serializing header and connection table back into V3000 CTfile syntax
- There are no frontend/backend or network layers; instead the architecture is organized as three main Rust sub-crates (namespaced modules) under one library:
header ←─ ctab ─→ write

##### README for additional insights
- Confirms focus on V3000 CTfile read/write primitives
- Points to an external article for design rationale
- Mentions only a test suite (no external services or deployment artifacts)

a. Main components
- Public API (`lib.rs`): exposes functions like `read_ctfile` and `write_ctfile`.
- Header module (`src/header`): parses and models the file header (metadata, version codes, scaling factors, timestamps).
- Connection-table module (`src/ctab`): data structures and parsers for atoms, bonds, R-groups, coordinates, implicit hydrogens, valences.
- Write module (`src/write`): takes in-memory Header + CT structures and emits V3000-compliant text blocks.
- Test Suite (cargo test): verifies parsing and serialization correctness.
b. Relationships and interactions
- The Public API depends on both header and ctab modules to build a complete in-memory representation.
- The write module depends on the same in-memory structures to serialize them back to disk.
- Error types propagate upward (header::error and ctab::error aggregated in public API).
c. Architectural patterns/design principles
- Modular decomposition by file format concerns (separate header vs. body).
- Clear separation of parsing vs. serialization logic.
- Strongly-typed domain model in Rust (enums for element kinds, bond configurations, etc.).
- Single library crate, no microservices—just internal modules.
d. Key technologies, frameworks, libraries
- Rust language and Cargo build system
- No external dependencies (pure Rust, no FFI)
- Rust’s error handling (`Result`, custom error enums)
- Rust fmt and lint tooling (rustfmt.toml)

##### Emphasize
- How errors bubble up (error.rs in header and ctab).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Disk
    DiskIn["Disk: .mol/.molfiles"]:::disk

    %% Public API
    PublicAPI["Public API\n(lib.rs)"]:::api
    click PublicAPI "https://github.com/metamolecular/trey/blob/main/src/lib.rs"

    %% Header Module
    subgraph "Header Module"
        direction TB
        HeaderMod["mod.rs"]:::parse
        click HeaderMod "https://github.com/metamolecular/trey/blob/main/src/header/mod.rs"
        HeaderParser["Header Parser\n(header.rs)"]:::parse
        click HeaderParser "https://github.com/metamolecular/trey/blob/main/src/header/header.rs"
        HeaderError["Error Definitions\n(error.rs)"]:::parse
        click HeaderError "https://github.com/metamolecular/trey/blob/main/src/header/error.rs"
        Comment["comment.rs"]:::parse
        click Comment "https://github.com/metamolecular/trey/blob/main/src/header/comment.rs"
        DimCode["dimensional_code.rs"]:::parse
        click DimCode "https://github.com/metamolecular/trey/blob/main/src/header/dimensional_code.rs"
        Float10["float10.rs"]:::parse
        click Float10 "https://github.com/metamolecular/trey/blob/main/src/header/float10.rs"
        Float12["float12.rs"]:::parse
        click Float12 "https://github.com/metamolecular/trey/blob/main/src/header/float12.rs"
        FortranFloat["fortran_float.rs"]:::parse
        click FortranFloat "https://github.com/metamolecular/trey/blob/main/src/header/fortran_float.rs"
        FortranInt["fortran_int.rs"]:::parse
        click FortranInt "https://github.com/metamolecular/trey/blob/main/src/header/fortran_int.rs"
        I2["i2.rs"]:::parse
        click I2 "https://github.com/metamolecular/trey/blob/main/src/header/i2.rs"
        I6["i6.rs"]:::parse
        click I6 "https://github.com/metamolecular/trey/blob/main/src/header/i6.rs"
        Name["name.rs"]:::parse
        click Name "https://github.com/metamolecular/trey/blob/main/src/header/name.rs"
        Scaling["scaling_factors.rs"]:::parse
        click Scaling "https://github.com/metamolecular/trey/blob/main/src/header/scaling_factors.rs"
        Timestamp["timestamp.rs"]:::parse
        click Timestamp "https://github.com/metamolecular/trey/blob/main/src/header/timestamp.rs"
    end

    %% Connection-Table Module
    subgraph "Connection-Table Module"
        direction TB
        CTabMod["mod.rs"]:::parse
        click CTabMod "https://github.com/metamolecular/trey/blob/main/src/ctab/mod.rs"
        ConnTableParser["ConnectionTable Parser\n(connection_table.rs)"]:::parse
        click ConnTableParser "https://github.com/metamolecular/trey/blob/main/src/ctab/connection_table.rs"
        CTabError["Error Definitions\n(error.rs)"]:::parse
        click CTabError "https://github.com/metamolecular/trey/blob/main/src/ctab/error.rs"
        atom["atom.rs"]:::parse
        click atom "https://github.com/metamolecular/trey/blob/main/src/ctab/atom.rs"
        atomKind["atom_kind.rs"]:::parse
        click atomKind "https://github.com/metamolecular/trey/blob/main/src/ctab/atom_kind.rs"
        implicitH["implicit_hydrogens.rs"]:::parse
        click implicitH "https://github.com/metamolecular/trey/blob/main/src/ctab/implicit_hydrogens.rs"
        bond["bond.rs"]:::parse
        click bond "https://github.com/metamolecular/trey/blob/main/src/ctab/bond.rs"
        bondKind["bond_kind.rs"]:::parse
        click bondKind "https://github.com/metamolecular/trey/blob/main/src/ctab/bond_kind.rs"
        bondConf["bond_configuration.rs"]:::parse
        click bondConf "https://github.com/metamolecular/trey/blob/main/src/ctab/bond_configuration.rs"
        coord["coordinate.rs"]:::parse
        click coord "https://github.com/metamolecular/trey/blob/main/src/ctab/coordinate.rs"
        coordDisp["coordination_display.rs"]:::parse
        click coordDisp "https://github.com/metamolecular/trey/blob/main/src/ctab/coordination_display.rs"
        crossing["crossing_bond.rs"]:::parse
        click crossing "https://github.com/metamolecular/trey/blob/main/src/ctab/crossing_bond.rs"
        element["element.rs"]:::parse
        click element "https://github.com/metamolecular/trey/blob/main/src/ctab/element.rs"
        elemList["element_list.rs"]:::parse
        click elemList "https://github.com/metamolecular/trey/blob/main/src/ctab/element_list.rs"
        Hdisp["hydrogen_display.rs"]:::parse
        click Hdisp "https://github.com/metamolecular/trey/blob/main/src/ctab/hydrogen_display.rs"
        idx["index.rs"]:::parse
        click idx "https://github.com/metamolecular/trey/blob/main/src/ctab/index.rs"
        idxList["index_list.rs"]:::parse
        click idxList "https://github.com/metamolecular/trey/blob/main/src/ctab/index_list.rs"
        rgroup["rgroup.rs"]:::parse
        click rgroup "https://github.com/metamolecular/trey/blob/main/src/ctab/rgroup.rs"
        subStruct["substructure.rs"]:::parse
        click subStruct "https://github.com/metamolecular/trey/blob/main/src/ctab/substructure.rs"
        subStructKind["substructure_kind.rs"]:::parse
        click subStructKind "https://github.com/metamolecular/trey/blob/main/src/ctab/substructure_kind.rs"
        superAtom["superatom.rs"]:::parse
        click superAtom "https://github.com/metamolecular/trey/blob/main/src/ctab/superatom.rs"
        valence["valence.rs"]:::parse
        click valence "https://github.com/metamolecular/trey/blob/main/src/ctab/valence.rs"
        charge["charge.rs"]:::parse
        click charge "https://github.com/metamolecular/trey/blob/main/src/ctab/charge.rs"
        decimal["decimal.rs"]:::parse
        click decimal "https://github.com/metamolecular/trey/blob/main/src/ctab/decimal.rs"
        collection["collection.rs"]:::parse
        click collection "https://github.com/metamolecular/trey/blob/main/src/ctab/collection.rs"
    end

    %% In-memory Model
    subgraph "In-Memory Model"
        direction TB
        HeaderStruct["Header Struct"]:::model
        ConnTableStruct["ConnectionTable Struct"]:::model
    end

    %% Write Module
    subgraph "Write Module"
        direction TB
        WriteMod["mod.rs"]:::serialize
        click WriteMod "https://github.com/metamolecular/trey/blob/main/src/write/mod.rs"
        BlockWriter["block.rs"]:::serialize
        click BlockWriter "https://github.com/metamolecular/trey/blob/main/src/write/block.rs"
        HeaderWriter["header.rs"]:::serialize
        click HeaderWriter "https://github.com/metamolecular/trey/blob/main/src/write/header.rs"
        ConnTableWriter["connection_table.rs"]:::serialize
        click ConnTableWriter "https://github.com/metamolecular/trey/blob/main/src/write/connection_table.rs"
        RGroupWriter["rgroup.rs"]:::serialize
        click RGroupWriter "https://github.com/metamolecular/trey/blob/main/src/write/rgroup.rs"
        WrapUtil["wrap.rs"]:::serialize
        click WrapUtil "https://github.com/metamolecular/trey/blob/main/src/write/wrap.rs"
    end

    %% Output Disk
    DiskOut["Disk: V3000 CTfile"]:::disk

    %% Test Suite
    subgraph "Test Suite"
        direction TB
        style TestSuite stroke-dasharray: 5 5
        TestSuite["cargo test\n(round-trip tests)"]:::test
    end

    %% Flows
    DiskIn -->|"text input"| HeaderParser
    DiskIn -->|"text input"| ConnTableParser
    HeaderParser --> HeaderStruct
    ConnTableParser --> ConnTableStruct
    PublicAPI --> HeaderParser
    PublicAPI --> ConnTableParser
    HeaderStruct --> ConnTableWriter
    ConnTableStruct --> ConnTableWriter
    HeaderStruct --> BlockWriter
    ConnTableStruct --> BlockWriter
    BlockWriter --> DiskOut
    PublicAPI --> TestSuite
    TestSuite --> PublicAPI

    %% Error flow
    HeaderError --> PublicAPI
    CTabError --> PublicAPI

    %% Styles
    classDef parse fill:#ADD8E6,stroke:#000
    classDef model fill:#90EE90,stroke:#000
    classDef serialize fill:#FFA500,stroke:#000
    classDef api fill:#ADD8E6,stroke:#000
    classDef disk fill:#CCCCCC,stroke:#000,shape:cylinder
    classDef test fill:#fff5e6,stroke:#FFA500,stroke-dasharray:5 5

    class PublicAPI api
    class DiskIn disk
    class DiskOut disk
    class TestSuite test
```
