# nethermindeth/starknet-abi architecture

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

- Interactive diagram: https://gitdiagram.com/nethermindeth/starknet-abi
- Repository: https://github.com/nethermindeth/starknet-abi

## Overview

Below are detailed instructions tailored to this project:

- Core Library Components:
▸ core (handles the main StarknetAbi class and associated logic)
▸ abi_types (defines the types used in encoding/decoding)
▸ decode and encode (encapsulate functions like decode_core_type, decode_from_params, encode_core_type, and their variants)
▸ dispatch (for the decoding dispatcher that efficiently handles multiple ABIs)
▸ exceptions (handles error scenarios)
▸ parse and utils (provide parsing functionalities and helper functions)
- Benchmarks & Testing:
– Benchmarks: Represent the “benchmarks” directory as a component that shows performance measurement and validation of encoding/decoding routines.
– Testing: Show the “tests” folder where unit tests are organized. Clearly mark how various test suites (e.g., test_decoder, test_dispatcher) validate specific functionalities. Although these are not part of the runtime library, they are crucial for ongoing quality.
- Documentation:
– The “docs” folder (using Sphinx) should be charted as the documentation generator, which maps out API details and guides (e.g., installation, quickstart). This component is key for external consumers.
- Build and Deployment Pipeline:
– Include the “.github/workflows” folder as the CI/CD component (GitHub Actions workflows), which supports automated testing, linting, and releases.
- External Interfaces:

##### Relationships and Data Flow
– The parsing process: JSON input → parse module → core module constructs a StarknetAbi instance.
– Encoding/Decoding: The core module calls either encode or decode submodules to process contract calls or event data.
– Dispatcher: If multiple ABIs are loaded, show how they are handed off to the “dispatcher” component.

##### Important Architectural Patterns and Design Principles
- Modular Design: Emphasize how each module (encode, decode, parse, etc.) is independently designed and can be updated, unit-tested, and maintained.
- Separation of Concerns: The clear separation between encoding, decoding, and parsing logic should be evident.
- API-Centric Structure: Show that the library is built primarily to expose a clean API interface for consumers (with the StarknetAbi class as the entry point).
- Extensibility: Note how the dispatcher supports the rapid loading of thousands of ABIs for efficient processing.

##### Relevant Technologies, Frameworks, and Tools
- Python (with dependencies managed by Poetry)
- GitHub Actions for CI/CD (indicate pipelines with .github/workflows)
- Sphinx for documentation (docs folder)
- Unit Testing frameworks (pytest or similar) as inferred from the “tests” directory organization

##### Following Elements
- Each component is clearly labeled – for example: “StarknetAbi Core”, “Encoding Module”, “Decoding Module”, “ABI Types”, “Dispatcher”, “Exceptions Manager”, “Benchmarks”, “Tests”, “Documentation”, “CI/CD Pipeline”, “External Clients.”

##### Final Advice
- Don’t oversimplify—highlight every important internal interaction and dependency.

## Diagram (Mermaid)

```mermaid
graph TD
    exClient("External Client (Data Pipeline)"):::external

    subgraph "Core Library (nethermind/starknet_abi)"
        STARK("StarknetAbi Core"):::internal
        ABIT("ABI Types"):::internal
        PARSE("Parse Module"):::internal
        ENCODE("Encode Module"):::internal
        DECODE("Decode Module"):::internal
        DISPATCH("Dispatcher Module"):::internal
        EXCEPT("Exceptions Manager"):::internal
        UTILS("Utility Functions"):::internal
    end

    bench("Benchmarks"):::support
    tests("Testing Suite"):::support
    docs("Documentation"):::documentation
    cicd("CI/CD Pipeline"):::cicd
    readme("External Client Usage Guidelines"):::documentation

    exClient -->|"calls"| STARK
    STARK -->|"parses_json"| PARSE
    PARSE -->|"returns_parsed_data"| STARK
    STARK -->|"encodes_data"| ENCODE
    STARK -->|"decodes_data"| DECODE
    ENCODE -->|"error_handling"| EXCEPT
    DECODE -->|"error_handling"| EXCEPT
    STARK -->|"dispatches_ABI"| DISPATCH
    UTILS -->|"supports"| PARSE
    UTILS -->|"supports"| ENCODE
    UTILS -->|"supports"| DECODE
    UTILS -->|"supports"| DISPATCH
    docs -->|"documents"| STARK
    tests -->|"validates"| STARK
    cicd -->|"runs"| tests

    classDef internal fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px
    classDef external fill:#BBDEFB,stroke:#1565C0,stroke-width:2px
    classDef support fill:#FFF9C4,stroke:#F57F17,stroke-width:2px
    classDef documentation fill:#F8BBD0,stroke:#AD1457,stroke-width:2px
    classDef cicd fill:#FFE082,stroke:#FBC02D,stroke-width:2px

    click STARK "https://github.com/nethermindeth/starknet-abi/blob/master/nethermind/starknet_abi/core.py"
    click ABIT "https://github.com/nethermindeth/starknet-abi/blob/master/nethermind/starknet_abi/abi_types.py"
    click DECODE "https://github.com/nethermindeth/starknet-abi/blob/master/nethermind/starknet_abi/decode.py"
    click ENCODE "https://github.com/nethermindeth/starknet-abi/blob/master/nethermind/starknet_abi/encode.py"
    click DISPATCH "https://github.com/nethermindeth/starknet-abi/blob/master/nethermind/starknet_abi/dispatch.py"
    click EXCEPT "https://github.com/nethermindeth/starknet-abi/blob/master/nethermind/starknet_abi/exceptions.py"
    click PARSE "https://github.com/nethermindeth/starknet-abi/blob/master/nethermind/starknet_abi/parse.py"
    click UTILS "https://github.com/nethermindeth/starknet-abi/blob/master/nethermind/starknet_abi/utils.py"
    click bench "https://github.com/nethermindeth/starknet-abi/tree/master/benchmarks/"
    click tests "https://github.com/nethermindeth/starknet-abi/tree/master/tests/"
    click docs "https://github.com/nethermindeth/starknet-abi/tree/master/docs/"
    click cicd "https://github.com/nethermindeth/starknet-abi/tree/master/.github/workflows/"
    click readme "https://github.com/nethermindeth/starknet-abi/blob/master/README.md"
```
