# asad/reactiondecoder architecture

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

- Interactive diagram: https://gitdiagram.com/asad/reactiondecoder
- Repository: https://github.com/asad/reactiondecoder

## Overview

##### Project type and purpose
- This is an open-source, Java/Maven-based command-line & API toolkit (“Reaction Decoder Tool – RDT”) for chemical reaction analysis. It provides three core functions:
a. Atom–Atom Mapping (AAM)
b. Reaction Annotation (identify bond changes & reaction centres)
c. Reaction Comparison (compute reaction similarity)

##### High-level layers and directories
- Presentation/CLI layer
- uk.ac.ebi.aamtool (“ReactionDecoder”, “Annotator”, “CommandLineOptions”)
- Standardization & parsing
- org.openscience.cdk.smiles, uk.ac.ebi.aamtool.ChemicalFormatParser, StandardizeReaction
- Mapping engine
- org.openscience.smsd (algorithms: McGregor, MCS+, VF2, r-graph, etc.)
- uk.ac.ebi.reactionblast.mapping (GameTheory, block mapping, cache…)
- Mechanism analysis
- uk.ac.ebi.reactionblast.mechanism (bond‐change calculators, reaction centre annotator)
- Fingerprinting & similarity
- uk.ac.ebi.reactionblast.fingerprints & signature
- IO & data layer
- tools/rxnfile (RXN reader/writer), interfaces/IDataSource, IDataStore
- External dependency
- CDK (org.openscience.cdk) for molecular objects
- Test suite
- src/test/java – unit/integration tests for mapping and AAM

##### Core components and interactions
1. User invokes `java –jar ReactionDecoder.jar` → CLI Parser (`CommandLineOptions`)
2. CLI dispatches to one of three jobs: AAM, ANNOTATE, COMPARE
3. Input reader (SMILES or RXN) using IO layer → produces CDK `IReaction`/`IAtomContainer`
4. StandardizeReaction normalizes molecules (2D/3D, stereochemistry)
5. Mapping engine (`ReactionMechanismTool`):
– Calls SMSD algorithms (McGregor, MCS+, VF2, r-graph) and/or GameTheoryMapper
– Produces `MappingSolution` containing the mapped `IReaction`
6. MechanismTool inspects `MappingSolution` → calculates bond changes, reaction centres
7. For COMPARE: two mapped reactions feed into fingerprint/signature generators → similarity score
8. Output formatter (TEXT, XML) writes result to console or file

##### Diagramming conventions
- Clear labels: use the package name or functional name (e.g., “Mapping Engine”)
- Rectangles (CLI / UI) – Blue

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation / CLI Layer
    subgraph "Presentation / CLI Layer"
        direction TB
        CLI["ReactionDecoder (CLI)"]:::cli
        CmdOpts["CommandLineOptions"]:::cli
        Annotator["Annotator"]:::cli
        ChemParser["ChemicalFormatParser"]:::cli
        Helper["Helper"]:::cli
        SimResult["SimilarityResult"]:::cli
    end

    %% IO & Data Layer
    subgraph "IO & Data Module"
        direction TB
        RXNReader["MDLRXNV2000Reader"]:::io
        RXNWriter["MDLV2000RXNWriter"]:::io
        IDataSource["IDataSource"]:::io
        IDataStore["IDataStore"]:::io
    end

    %% Standardization & Parsing
    subgraph "Standardization & Parsing"
        direction TB
        CanonSmi["CanonSmiAdapter"]:::core
        StdReaction["StandardizeReaction"]:::core
    end

    %% Mapping Engine
    subgraph "Mapping Engine"
        direction TB
        subgraph "SMSD Algorithms"
            direction TB
            AAM["AtomAtomMapping"]:::core
            BaseMap["BaseMapping"]:::core
            Algorithms["Algorithm Packages"]:::core
        end
        subgraph "ReactionBlast Mapping"
            direction TB
            GTFactory["GameTheoryFactory"]:::core
            BlockMapper["BlockMapper"]:::core
            CacheComp["Cache"]:::core
            CDKBuilder["CDKReactionBuilder"]:::core
        end
    end

    %% Mechanism Analysis Module
    subgraph "Mechanism Analysis"
        direction TB
        MechTool["ReactionMechanismTool"]:::core
        BondCalc["BondChangeCalculator"]:::core
        BondAnnot["BondChangeAnnotator"]:::core
        MapSolution["MappingSolution"]:::core
    end

    %% Fingerprinting & Similarity
    subgraph "Fingerprinting & Similarity"
        direction TB
        FingerGen["FingerprintGenerator"]:::core
        FingerPrint["ReactionFingerprinter"]:::core
        MolSig["RBlastMoleculeSignature"]:::core
        SigMatch["SignatureMatcher"]:::core
    end

    %% External CDK Library
    CDK["CDK Library"]:::external

    %% Test Suite
    subgraph "Test Suite"
        direction TB
        MCSTest["MCSTest"]:::test
        RXNMappingTest["RXNMappingTest"]:::test
        ComplexCases["ComplexCases"]:::test
    end

    %% Data Flow
    User(("User")):::external --> CLI
    CLI --> CmdOpts
    CLI --> Annotator
    CmdOpts --> RXNReader
    CmdOpts --> RXNWriter
    RXNReader --> CanonSmi
    CanonSmi --> StdReaction
    StdReaction --> AAM
    AAM --> MapSolution
    BaseMap --> MapSolution
    Algorithms --> AAM
    GTFactory --> AAM
    BlockMapper --> AAM
    CacheComp --> BlockMapper
    CDKBuilder --> AAM
    MapSolution --> MechTool
    MechTool --> BondCalc
    MechTool --> BondAnnot
    MapSolution --> FingerGen
    FingerGen --> FingerPrint
    FingerPrint --> MolSig
    MolSig --> SigMatch
    SigMatch --> SimResult
    SimResult --> CLI
    RXNWriter --> User

    %% Dependencies to CDK
    CanonSmi --- CDK
    StdReaction --- CDK
    AAM --- CDK
    BaseMap --- CDK
    Algorithms --- CDK
    CDKBuilder --- CDK
    MechTool --- CDK
    FingerGen --- CDK

    %% Tests
    AAM --> MCSTest
    Annotator --> RXNMappingTest
    CanonSmi --> ComplexCases

    %% Click Events
    click CLI "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/aamtool/ReactionDecoder.java"
    click CmdOpts "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/aamtool/CommandLineOptions.java"
    click Annotator "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/aamtool/Annotator.java"
    click ChemParser "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/aamtool/ChemicalFormatParser.java"
    click Helper "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/aamtool/Helper.java"
    click SimResult "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/aamtool/SimilarityResult.java"
    click CanonSmi "https://github.com/asad/reactiondecoder/blob/master/src/main/java/org/openscience/cdk/smiles/CanonSmiAdapter.java"
    click StdReaction "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/tools/StandardizeReaction.java"
    click AAM "https://github.com/asad/reactiondecoder/blob/master/src/main/java/org/openscience/smsd/AtomAtomMapping.java"
    click BaseMap "https://github.com/asad/reactiondecoder/blob/master/src/main/java/org/openscience/smsd/BaseMapping.java"
    click Algorithms "https://github.com/asad/reactiondecoder/tree/master/src/main/java/org/openscience/smsd/algorithm"
    click GTFactory "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/mapping/algorithm/GameTheoryFactory.java"
    click BlockMapper "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/mapping/blocks/BlockMapper.java"
    click CacheComp "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/mapping/cache/Cache.java"
    click CDKBuilder "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/mapping/container/CDKReactionBuilder.java"
    click MechTool "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/mechanism/ReactionMechanismTool.java"
    click BondCalc "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/mechanism/BondChangeCalculator.java"
    click BondAnnot "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/mechanism/BondChangeAnnotator.java"
    click MapSolution "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/mechanism/MappingSolution.java"
    click FingerGen "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/fingerprints/FingerprintGenerator.java"
    click FingerPrint "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/fingerprints/ReactionFingerprinter.java"
    click MolSig "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/signature/RBlastMoleculeSignature.java"
    click SigMatch "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/signature/SignatureMatcher.java"
    click RXNReader "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/tools/rxnfile/MDLRXNV2000Reader.java"
    click RXNWriter "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/tools/rxnfile/MDLV2000RXNWriter.java"
    click IDataSource "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/interfaces/IDataSource.java"
    click IDataStore "https://github.com/asad/reactiondecoder/blob/master/src/main/java/uk/ac/ebi/reactionblast/interfaces/IDataStore.java"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef core fill:#E6F5D0,stroke:#4F8A10,color:#4F8A10,stroke-width:1px;
    classDef io fill:#F0F0F0,stroke:#888888,color:#555555,stroke-width:1px;
    classDef external fill:#F4E1FF,stroke:#9B59B6,color:#9B59B6,stroke-width:1px,stroke-dasharray: 5 5;
    classDef test fill:#F5F5F5,stroke:#AAAAAA,color:#777777,stroke-dasharray: 5 5;
```
