# damianb-bitflipper/algopytest architecture

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

- Interactive diagram: https://gitdiagram.com/damianb-bitflipper/algopytest
- Repository: https://github.com/damianb-bitflipper/algopytest

## Overview

##### Project Type and Purpose
- This is a Python library/Pytest plugin (not a web server or UI) whose sole purpose is to simplify writing tests for Algorand smart contracts by providing ready-made fixtures and helper functions.
- It acts as a middleware between Pytest and an Algorand sandbox, hiding boilerplate for account setup, contract deployment, transactions, and cleanup.

##### Key Architectural Components
From the file tree and README, the main subsystems are:
a. Plugin Core (algopytest package)
- account_ops.py – account creation/funding/cleanup
- client_ops.py – Algod client creation, SDK wrappers
- transaction_ops.py – building/submitting transactions
- config_params.py – reading environment variables (SANDBOX_DIR, INITIAL_FUNDS_ACCOUNT, etc.)
- fixtures.py – Pytest hook registrations, fixture definitions (owner, user1, smart_contract_id, etc.)
- entities.py, utils.py, type_stubs.py – supporting data models, helpers, and typing
b. External Dependencies
- Algorand Sandbox (Docker-based local network)
- Algorand SDK (algosdk)
- Pytest (test runner and plugin host)
c. Demos
- A set of sample projects under /demos illustrating how end-users consume the plugin
d. Documentation & CI
- docs/ – Read-the-Docs source for docs generation
- .github/workflows/ci.yml – GitHub Actions for tests, linting, coverage
- pre-commit, mypy, flake8 configs for quality checks

##### Interactions and Data Flows
- Pytest test suite invokes fixtures provided by AlgoPytest (via pytest_plugin hooks in fixtures.py).
- A fixture (e.g. smart_contract_id) calls create_app (in client_ops) which:
1. Reads config_params to find SANDBOX_DIR and INITIAL_FUNDS_ACCOUNT
2. Uses account_ops to create/fund user accounts
3. Deploys the approval/clear programs to the sandbox via Algod client (client_ops + transaction_ops)
4. Yields an app_id back to the test
5. On teardown, runs cleanup (delete app, close accounts)
- Tests (in /tests or individual demos) call helper functions (update_app, call_app, opt_in_app) which invoke transaction_ops and client_ops against the sandbox.
- The docs build system reads the same modules to generate reference docs.

##### Highlighted Architectural Patterns & Principles
- Plugin Pattern: leveraging pytest hooks to auto-register fixtures
- Dependency Injection via fixtures: injecting clients, accounts, app_ids into tests
- Clean-up via context managers/yield fixtures to guarantee teardown
- Separation of concerns:
- config_params only reads env vars
- account_ops only manages accounts
- transaction_ops only builds and submits transactions
- Extensibility: new fixtures or helpers can be added in fixtures.py or new modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    PytestRunner["Pytest Runner"]:::external
    EnvConfig["Environment Configuration\n(env vars)"]:::external
    AlgorandSandbox["Algorand Sandbox\n(Docker Network)"]:::external

    %% User Code
    subgraph "Demos & Test Suites"
        direction TB
        Demos["Demos (sample projects)"]:::user
        Tests["Test Suite\n(tests/)"]:::user
    end

    %% Core Plugin
    subgraph "AlgoPytest Plugin Core"
        direction TB
        Fixtures["fixtures.py\n(Pytest hooks)"]:::internal
        ConfigParams["config_params.py\n(env reader)"]:::internal
        ClientOps["client_ops.py\n(Algod client)"]:::internal
        AccountOps["account_ops.py\n(account management)"]:::internal
        TransactionOps["transaction_ops.py\n(txn builder)"]:::internal
        Entities["entities.py\n(data models)"]:::internal
        Utils["utils.py\n(helpers)"]:::internal
        TypeStubs["type_stubs.py\n(type definitions)"]:::internal
    end

    %% CI & Docs
    subgraph "CI & Docs Pipeline"
        direction TB
        DocsSource["Documentation Source\n(docs/)"]:::external
        CIWorkflow["CI Workflow\n(.github/workflows/ci.yml)"]:::external
    end

    %% Relationships
    PytestRunner -->|pytest_fixture_request| Fixtures
    Fixtures -->|reads env| ConfigParams
    EnvConfig -->|provides vars| ConfigParams

    Fixtures -->|create client| ClientOps
    Fixtures -->|setup accounts| AccountOps
    Fixtures -->|deploy app| TransactionOps

    ClientOps -->|uses sdk| AlgorandSandbox
    AccountOps -->|fund/delete accounts| AlgorandSandbox
    TransactionOps -->|submit transactions| AlgorandSandbox

    Demos -->|use fixtures| Fixtures
    Tests -->|use helpers| ClientOps
    Tests -->|use fixtures| Fixtures

    DocsSource -->|imports modules| Entities
    DocsSource -->|imports modules| ConfigParams
    CIWorkflow -->|runs tests| Tests
    CIWorkflow -->|lints & type checks| Utils

    %% Click Events
    click AccountOps "https://github.com/damianb-bitflipper/algopytest/blob/master/algopytest/account_ops.py"
    click ClientOps "https://github.com/damianb-bitflipper/algopytest/blob/master/algopytest/client_ops.py"
    click TransactionOps "https://github.com/damianb-bitflipper/algopytest/blob/master/algopytest/transaction_ops.py"
    click ConfigParams "https://github.com/damianb-bitflipper/algopytest/blob/master/algopytest/config_params.py"
    click Fixtures "https://github.com/damianb-bitflipper/algopytest/blob/master/algopytest/fixtures.py"
    click Entities "https://github.com/damianb-bitflipper/algopytest/blob/master/algopytest/entities.py"
    click Utils "https://github.com/damianb-bitflipper/algopytest/blob/master/algopytest/utils.py"
    click TypeStubs "https://github.com/damianb-bitflipper/algopytest/blob/master/algopytest/type_stubs.py"
    click Demos "https://github.com/damianb-bitflipper/algopytest/tree/master/demos/"
    click Tests "https://github.com/damianb-bitflipper/algopytest/tree/master/tests/"
    click DocsSource "https://github.com/damianb-bitflipper/algopytest/tree/master/docs/"
    click CIWorkflow "https://github.com/damianb-bitflipper/algopytest/blob/master/.github/workflows/ci.yml"

    %% Styles
    classDef internal fill:#e0ffe0,stroke:#2d7f2d,color:#063;
    classDef external fill:#cce5ff,stroke:#255d91,color:#033;
    classDef user fill:#fff2cc,stroke:#997a00,color:#663300;
```
