# tucan-nest/tucan architecture

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

- Interactive diagram: https://gitdiagram.com/tucan-nest/tucan
- Repository: https://github.com/tucan-nest/tucan

## Overview

##### Project type and purpose
- TUCAN is a Python library/tool, not a web or full‐stack app.

##### Main architectural components
a. IO Layer
– tucan/io/molfile_reader, molfile_v2000_reader, molfile_v3000_reader, molfile_writer
– Exception classes (tucan/io/exception.py)
b. Parser Layer
– ANTLR‐generated parser (tucan/parser/*.py, *.g4, *.bnfplayground)
– parser/parser.py orchestrates tokenization and AST → graph conversion
c. Core Graph Model & Utilities
– Graph representation (likely networkx or custom in tucan/graph_utils.py)
– Element and graph attributes (element_attributes.py, graph_attributes.py)
– Test utilities (tucan/test_utils.py)
d. Canonicalization
e. Serialization
– tucan/serialization.py: emit final TUCAN string (e.g., C2H4O2/(…))
f. Visualization
– tucan/visualization.py: optional graph‐to‐image or Jupyter output
g. Packaging & Configuration
– pyproject.toml: dependencies, build backend (poetry/flake8, etc.)
– .github/workflows: CI, formatting, dataset generation
– docs folder: demo notebooks, static images

##### Relationships and data flows
- molfile input (.mol)
↓
- IO Layer reads file → raw token stream or text
↓
- Parser Layer builds intermediate graph structure (nodes=atoms, edges=bonds)
↓
- Graph Utilities annotate degrees, attributes
↓
- Canonicalization orders/renumbers graph → canonical graph
↓
- Serialization produces TUCAN string
↓
- Visualization (optional) renders 2D/3D depiction from canonical graph
- Tests call each layer individually (unit tests for IO, parser, canonicalization, serialization)
- CI workflows run tests, format checks, build docs

##### Architectural patterns and design principles
- Modular Python package: each subpackage focuses on one responsibility
- Use of generated parser code (ANTLR) to separate grammar from business logic
- Test‐driven design: extensive tests for every component

##### Technologies & frameworks
- Python ≥3.10
- ANTLR‐generated parser (tucan.parser)
- Pytest for testing
- Jupyter notebooks (docs)
- GitHub Actions (CI, formatting)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs and Outputs
    MOL_FILE(("​.mol File")):::storage
    PYPROJECT(("pyproject.toml")):::storage
    TUCAN_STR(("TUCAN String Output")):::storage

    %% Runtime Layers
    subgraph "Runtime Modules"
        IO["IO Layer\n(readers & exceptions)"]:::runtime
        PARSER["Parser Layer\n(ANTLR-generated)"]:::runtime
        GRAPHUTILS["Graph Utils\n(attributes & test utils)"]:::runtime
        CANON["Canonicalization"]:::runtime
        SERIAL["Serialization"]:::runtime
        VIS["Visualization"]:::runtime
    end

    %% Support Modules
    subgraph "Support Modules"
        TESTS["Tests"]:::support
        DOCS["Documentation\n(notebooks & images)"]:::support
        CI["CI Workflows"]:::support
    end

    %% Data Flow
    MOL_FILE -->|"raw text"| IO
    IO -->|"token stream / AST"| PARSER
    PARSER -->|"Graph object"| GRAPHUTILS
    GRAPHUTILS -->|"annotated Graph"| CANON
    CANON -->|"canonical Graph"| SERIAL
    SERIAL -->|"TUCAN string"| TUCAN_STR
    CANON -->|"Graph object"| VIS
    VIS -->|"image / Jupyter output"| DOCS

    %% Support Flows
    TESTS --> IO
    TESTS --> PARSER
    TESTS --> CANON
    TESTS --> SERIAL
    CI --> TESTS
    CI --> DOCS
    CI --> PYPROJECT

    %% Click Events for Component Mapping
    click IO "https://github.com/tucan-nest/tucan/tree/bliss-canonicalization/tucan/io/"
    click IO "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/io/molfile_reader.py"
    click IO "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/io/molfile_v2000_reader.py"
    click IO "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/io/molfile_v3000_reader.py"
    click IO "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/io/molfile_writer.py"
    click IO "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/io/exception.py"
    click PARSER "https://github.com/tucan-nest/tucan/tree/bliss-canonicalization/tucan/parser/"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/parser.py"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/tucan.g4"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/tucan.ebnf"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/tucan.bnfplayground"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/tucan.tokens"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/tucanLexer.py"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/tucanParser.py"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/tucanListener.py"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/tucan.interp"
    click PARSER "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/parser/tucanLexer.interp"
    click GRAPHUTILS "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/graph_utils.py"
    click GRAPHUTILS "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/element_attributes.py"
    click GRAPHUTILS "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/graph_attributes.py"
    click GRAPHUTILS "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/test_utils.py"
    click CANON "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/canonicalization.py"
    click SERIAL "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/serialization.py"
    click VIS "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/tucan/visualization.py"
    click PYPROJECT "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/pyproject.toml"
    click CI "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/.github/workflows/ci.yml"
    click CI "https://github.com/tucan-nest/tucan/blob/bliss-canonicalization/.github/workflows/format_dataset.yml"
    click DOCS "https://github.com/tucan-nest/tucan/tree/bliss-canonicalization/docs/"
    click TESTS "https://github.com/tucan-nest/tucan/tree/bliss-canonicalization/tests/"

    %% Styles
    classDef runtime fill:#A2D9CE,stroke:#117A65,color:#000
    classDef support fill:#F9E79F,stroke:#B9770E,color:#000
    classDef storage fill:#D5F5E3,stroke:#239B56,color:#000
    class IO,PARSER,GRAPHUTILS,CANON,SERIAL,VIS runtime
    class TESTS,DOCS,CI support
    class MOL_FILE,PYPROJECT,TUCAN_STR storage
```
