# r-near/near-sdk-py architecture

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

- Interactive diagram: https://gitdiagram.com/r-near/near-sdk-py
- Repository: https://github.com/r-near/near-sdk-py

## Overview

##### Main Components
- Core NEAR Functionality:
- This is primarily under the “src/near” directory and includes files like context.py, storage.py, math.py, etc.
- It handles low-level blockchain interactions (e.g., blockchain context, economics, registers, and validators).
- NEAR SDK Python Interface:
- Found under “src/near_sdk_py” and its subdirectories. This is the heart of the SDK, offering the core “Contract” class, decorators (e.g., @call, @view, @init), and a rich set of utilities.
- Includes the Pythonic collections API (in the “collections” subdirectory) to provide a dictionary-like storage interface as well as multiple collection types (lookup maps, unordered maps/sets, tree maps, vectors).
- Promises and Cross-Contract Calls:
- Located in both “src/near” (promises.py) and “src/near_sdk_py/promises”. This is crucial for implementing cross-contract calls with method chaining, callbacks, and batch operations.
- Documentation and Examples:
- The “docs” directory (with separate sections for collections and promises) shows how the design is meant to be used.
- The README and the examples therein illustrate how developers will write contracts that interact with the SDK.
- Testing and Integration:
- “integration_tests” and “tests” directories include integration tests and performance benchmarks that validate the contract behaviors, simulate a blockchain environment, and ensure performance.
- CI/CD and DevOps:
- The “.github” directory with workflows (e.g., lint, release, tests) indicates automated quality checks and deployment processes.

##### Relationships and Interactions
- The core module (src/near) provides low-level blockchain functions that underpin the higher-level SDK.
- The NEAR SDK Python interface (src/near_sdk_py) wraps these lower-level functions into an easier-to-use, object-oriented API.
- The Contract base class exposes a Pythonic interface for contract authors (illustrated in the README), and it leverages both collections for storage and promises for cross-contract calls.
- The “docs” and “integration_tests” serve as validations and usage examples that interact directly with these modules.
- Build tools and CI/CD workflows ensure code quality and maintain the integrity of these interactions.

##### Architectural Patterns and Design Principles
- Modularization: The system is clearly split into modules with specific concerns (blockchain context, storage, collections, promises). Each module interacts via well-defined interfaces.
- Decorator Pattern: The use of Python decorators (e.g., @init, @call, @view) to designate behavior in contract methods is a key aspect.
- Layered Architecture: From low-level blockchain operations (e.g., context, economics) up through the SDK layer (contracts and API utilities) to the application-level (user contracts), there’s a clear separation.
- Testing and CI Integration: Integration tests and performance benchmarks emphasize the need for robust, repeatable testing.

##### Final Recommendations for the Principal Software Engineer
- Dependency flows and interactions (for example, show how data flows from a contract method call, through the SDK decorators, invoking lower-level blockchain context operations, and then returning results to the contract).
- Use annotations where needed to note design decisions (e.g., use of decorators for method dispatch, promise chaining for asynchronous cross-contract calls, and modular separation for maintainability).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Blockchain Core
    subgraph "Blockchain Core"
        Core["Core NEAR (src/near)"]:::core
        CorePromises["Promises (src/near/promises)"]:::core
    end

    %% SDK Interface
    subgraph "SDK Interface"
        SDK["NEAR SDK Python Interface (src/near_sdk_py)"]:::sdk
        Contract["Contract & Decorators"]:::sdk
        Utilities["Utilities (input, log, constants)"]:::sdk
        subgraph "Collections API"
            Collections["Collections (src/near_sdk_py/collections)"]:::sdk
        end
        subgraph "Promises API"
            SDKPromises["Promises (src/near_sdk_py/promises)"]:::sdk
        end
    end

    %% Developer & Documentation
    subgraph "Developer & Documentation"
        Docs["Docs & Examples (docs, README.md)"]:::docs
    end

    %% Testing and CI/CD
    subgraph "Testing and CI/CD"
        Testing["Testing (tests & integration_tests)"]:::testing
        CI["CI/CD (.github workflows)"]:::cid
    end

    %% Relationships
    Docs -->|"uses"| SDK
    Docs -->|"demonstrates"| Contract

    SDK -->|"wraps"| Core

    Contract -->|"calls"| Core
    Contract -->|"calls"| Utilities
    Contract -->|"uses"| Collections
    Contract -->|"callsPromises"| SDKPromises

    SDKPromises -->|"chainsTo"| CorePromises

    Testing -->|"validates"| Core
    Testing -->|"validates"| SDK
    Testing -->|"validates"| Collections
    Testing -->|"validates"| SDKPromises

    CI -->|"enforces"| Testing

    %% Click Events
    click Core "https://github.com/r-near/near-sdk-py/tree/main/src/near"
    click SDK "https://github.com/r-near/near-sdk-py/tree/main/src/near_sdk_py"
    click Collections "https://github.com/r-near/near-sdk-py/tree/main/src/near_sdk_py/collections"
    click CorePromises "https://github.com/r-near/near-sdk-py/tree/main/src/near/promises"
    click SDKPromises "https://github.com/r-near/near-sdk-py/tree/main/src/near_sdk_py/promises"
    click Docs "https://github.com/r-near/near-sdk-py/tree/main/docs"
    click Testing "https://github.com/r-near/near-sdk-py/tree/main/tests"
    click CI "https://github.com/r-near/near-sdk-py/blob/main/.github"

    %% Styles
    classDef core fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef sdk fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef docs fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef testing fill:#fdf2e9,stroke:#333,stroke-width:2px;
    classDef cid fill:#e8daef,stroke:#333,stroke-width:2px;
```
