# ar-io/ar-io-network-process architecture

> Architecture diagram of the GitHub repository ar-io/ar-io-network-process, 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/ar-io/ar-io-network-process
- Repository: https://github.com/ar-io/ar-io-network-process

## Overview

##### Project Type & Purpose
- This project is an implementation of the AO/IO network contract, written in Lua. It provides the core functionality for managing the network state, handling transactions, and enforcing network rules on the Arweave network.
- The README highlights key aspects such as deployments (for testnet, devnet, and mainnet), monitoring, and testing strategies. Its primary function is to serve as a “process” that interacts with the network via the aos CLI and automated deployment scripts.

##### File Structure Analysis
- Top-Level Organization: Notice the separation into distinct folders:
- src – Contains the core logic files (process.lua, main.lua, and modules for events, state, token, etc.)
- cron – Houses scheduled tasks (for example, cron/main.lua) which likely handle periodic updates or maintenance logic.
- tests – Divided into unit and integration tests (using Busted and ao-loader), including monitor-specific tests.
- tools – Provides utilities for bootstrapping, evolving the network process, bundling, and other operations.
- spec – Contains specification files and further tests, detailing individual behaviors of modules.
- Configuration & CI/CD: Files like .github/workflows (for GitHub Actions), .luacheckrc, and package configuration files (package.json, rockspec, etc.) indicate a setup with continuous integration, code formatting, linting, and dependency management.

##### Key Components
a. Process Core:
- The heart of the application is in the Lua source code in the src folder (process.lua, main.lua, and supporting modules such as token.lua, balances.lua, etc.).
- The process is loaded by the aos CLI (as shown in the README) and represents the running smart contract logic interacting with the on-chain Arweave network.

b. Cron/Scheduled Tasks:
- The cron folder contains scheduled Lua scripts (e.g., cron/main.lua) that trigger periodic processes such as state updates or network maintenance tasks.

c. Tests & Validation:
- The tests folder is well-structured to include unit and integration tests. There are sub-components for core functionality (like balances, epochs, and vaults) as well as monitor tests that use testcontainers and docker-compose.

d. Monitoring & Deployment:
- The README details the monitoring setup with workflows like monitor.yaml and monitor_ad_hoc.yaml.
- Tools such as the evolve module in tools/evolve.mjs are used for deployment updates, showing the connection between development and continuous deployment pipelines.
- External services: The project interacts with external nodes (via aoconnect) and the AO/IO network on Arweave. Represent endpoints like CU (compute unit) and network endpoints for mainnet, testnet, and devnet.

e. Build & Dependency Management:
- Configuration management is handled via LuaRocks (dependencies in the rockspec file), node (package.json), and CI configurations.
- Components for code formatting (stylua), linting (luacheckrc), and version management (.nvmrc).

##### Architectural Patterns & Relationships
- Layered Architecture: Separate logical layers can be highlighted:
- Interface/Deployment Layer: Tools that allow external commands (aos CLI, evolve.mjs, and cron scheduling).
- Core Business Logic: Modules within the src folder that process events, maintain network state, and enforce network rules.
- Testing & Monitoring Layer: Unit and integration tests validating the core logic; monitor tests checking live system invariants.
- Data Flow: Indicate how network transactions (triggered via aos or external API calls) flow into the process core, update the state (state/init.lua), and result in further actions, possibly with responses being validated by the monitoring systems.
- Code Deployment: Show how changes get integrated via GitHub Actions workflows (build, tick, monitor) and then deployed to different network environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interface/Deployment Layer
    subgraph "Interface/Deployment Layer"
        DeployTools("CLI & Deployment Tools"):::deploy
        Cron("Scheduled Cron Tasks"):::schedule
    end

    %% Core Business Logic
    subgraph "Core Business Logic"
        ProcessCore("Network Process Core"):::core
    end

    %% Testing & Monitoring Layer
    subgraph "Testing & Monitoring Layer"
        Tests("Tests Suite"):::test
        Spec("Specification Suite"):::test
        GHWorkflows("GitHub Workflows"):::monitor
    end

    %% Build & Dependency Management
    subgraph "Build & Dependency Management"
        PKG("package.json"):::config
        Rockspec("ar-io-ao-0.1-1.rockspec"):::config
        Luacheck(" .luacheckrc"):::config
        Nvmrc(".nvmrc"):::config
    end

    %% External Services
    subgraph "External Services"
        Arweave("External Arweave Network"):::external
        Aoconnect("Aoconnect Service"):::external
    end

    %% Relationships
    DeployTools -->|"triggers"| ProcessCore
    Cron -->|"triggers"| ProcessCore

    ProcessCore -->|"interacts"| Arweave
    ProcessCore -->|"interacts"| Aoconnect

    ProcessCore <-->|"monitored_by"| Tests
    ProcessCore <-->|"monitored_by"| Spec
    ProcessCore <-->|"monitored_by"| GHWorkflows

    PKG -->|"build_config"| ProcessCore
    Rockspec -->|"build_config"| ProcessCore
    Luacheck -->|"build_config"| ProcessCore
    Nvmrc -->|"build_config"| ProcessCore

    %% Click Events
    click ProcessCore "https://github.com/ar-io/ar-io-network-process/tree/develop/src"
    click Cron "https://github.com/ar-io/ar-io-network-process/blob/develop/cron/main.lua"
    click DeployTools "https://github.com/ar-io/ar-io-network-process/blob/develop/tools/evolve.mjs"
    click Tests "https://github.com/ar-io/ar-io-network-process/tree/develop/tests"
    click Spec "https://github.com/ar-io/ar-io-network-process/tree/develop/spec"
    click GHWorkflows "https://github.com/ar-io/ar-io-network-process/tree/develop/.github/workflows"
    click PKG "https://github.com/ar-io/ar-io-network-process/blob/develop/package.json"
    click Rockspec "https://github.com/ar-io/ar-io-network-process/blob/develop/ar-io-ao-0.1-1.rockspec"
    click Luacheck "https://github.com/ar-io/ar-io-network-process/blob/develop/.luacheckrc"
    click Nvmrc "https://github.com/ar-io/ar-io-network-process/blob/develop/.nvmrc"

    %% Styles
    classDef core fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef schedule fill:#B8E0A7,stroke:#333,stroke-width:2px;
    classDef deploy fill:#FFC107,stroke:#333,stroke-width:2px;
    classDef test fill:#F7A1A1,stroke:#333,stroke-width:2px;
    classDef monitor fill:#F7D6A1,stroke:#333,stroke-width:2px;
    classDef config fill:#FFF799,stroke:#333,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
