# airchains-network/junction architecture

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

- Interactive diagram: https://gitdiagram.com/airchains-network/junction
- Repository: https://github.com/airchains-network/junction

## Overview

##### Project type and purpose
- Junction is a blockchain “settlement layer” built on the Cosmos SDK. It compiles to a single monolithic binary (`junctiond`) that embeds:
- A Tendermint consensus engine (external dependency)
- An ABCI application (`app/app.go`)
- Two feature modules: `x/wasm` and `x/rollup`
- CLI front‐end (`cmd/junctiond`)
- gRPC/REST API layer (generated under `api/junction/rollup`).

##### File structure
- Top-level binaries and scripts:
- `cmd/junctiond/` – CLI commands and initialization
- `app/` – Cosmos SDK application wiring (module manager, upgrade handlers, genesis, params)
- `x/wasm/` – WebAssembly smart-contract module (keepers, handlers, IBC support)
- `x/rollup/` – Rollup Layer-2 module (keeper, CLI client, IBC plugin)
- `api/junction/rollup/` – gRPC/Protobuf stubs and Pulsar event bindings
- `proto/` – .proto definitions for CLI, gRPC, OpenAPI, and cross-chain IBC
- Support folders:
- `scripts/` – build, devnet, relayer tests
- `docs/` – generated API docs and OpenAPI specs
- `tests/` – E2E and system tests targeting IBC, governance, rollup flows

##### README for additional insights
- Core modules: `wasm` for smart contracts, `rollup` for Layer-2 batching & proof integration
- IBC integration and staking economics baked into the rollup module
- Emphasis on high throughput batch processing, state verification via external provers

##### Main components
a. External layers:
– CLI / REST / gRPC client
– External Tendermint process (p2p + consensus)
– External prover service or ZK engine
– Other Cosmos chains (IBC peers)
b. Junction node (“junctiond” binary):
– ABCI server (receives consensus and mempool messages)
– App module manager (registers `x/wasm`, `x/rollup`, standard cosmos modules like auth, bank, staking)
– KVStore (LevelDB) / State database
– gRPC server (auto-generated from `api/junction`)
c. Feature modules:
– WASM module:
- Contract keeper & Wasmer engine
- IBC plugin hooks for cross-chain contract calls
– Rollup module:
- Keeper for batch submission, prover integration, staking
- IBC plugin for submitting proofs & packet transfers
d. Interactions:
– CLI / gRPC → Tendermint ABCI → App → Modules → KVStore
– Modules → IBC → Other Chains
– Rollup keeper → Prover service → Commitment verification → KVStore
– WASM keeper → Wasmer VM → Custom contracts

##### Architectural patterns and principles
- Modular Cosmos SDK design: Each domain in its own Go module under `x/`
- Separation of concerns: Consensus (Tendermint) vs. State & Logic (ABCI) vs. API clients
- Plugin-style integration: WASM engine plugged into the SDK, rollup proof system abstracted via external service
- Protobuf-first API: gRPC & REST stubs auto-generated from `proto/` definitions

## Diagram (Mermaid)

```mermaid
graph TD
    CLI["CLI/REST/gRPC Client"]:::client
    TM["Tendermint (p2p + consensus)"]:::consensus
    IBCREL["IBC Relayer"]:::consensus

    subgraph "junctiond (ABCI App)"
        ABCI["ABCI Server"]:::app
        GM["App Module Manager"]:::app
        DB["KVStore (LevelDB)"]:::storage
        GRPC["gRPC/REST Server"]:::api

        subgraph "Core Modules"
            Auth["auth"]:::module
            Bank["bank"]:::module
            Staking["staking"]:::module
            Gov["gov"]:::module
        end

        subgraph "x/wasm Module"
            WasmKeeper["WASM Keeper & Wasmer VM"]:::module
            WasmIBC["IBC Plugin Hooks"]:::module
        end

        subgraph "x/rollup Module"
            RollupKeeper["Rollup Keeper"]:::module
            RollupIBC["Rollup IBC Plugin"]:::module
        end
    end

    Prover["External Prover Service"]:::external
    OtherChain["Other Cosmos Chains"]:::external

    CLI -->|HTTP/gRPC| GRPC
    CLI -->|TX Broadcast| TM
    TM -->|ABCI calls| ABCI
    ABCI -->|"dispatch to"| GM
    GM -->|module calls| Auth
    GM -->|module calls| Bank
    GM -->|module calls| Staking
    GM -->|module calls| Gov
    GM -->|module calls| WasmKeeper
    GM -->|module calls| RollupKeeper
    Auth -->|store/query| DB
    Bank -->|store/query| DB
    Staking -->|store/query| DB
    Gov -->|store/query| DB
    WasmKeeper -->|store/query| DB
    RollupKeeper -->|store/query| DB
    WasmIBC -->|IBC packets| OtherChain
    RollupIBC -->|IBC packets| OtherChain
    RollupKeeper -->|ZK Proof RPC| Prover
    Prover -->|Proof Response| RollupKeeper

    click CLI "https://github.com/airchains-network/junction/tree/main/cmd/junctiond"
    click ABCI "https://github.com/airchains-network/junction/blob/main/app/app.go"
    click WasmKeeper "https://github.com/airchains-network/junction/blob/main/x/wasm/module.go"
    click WasmIBC "https://github.com/airchains-network/junction/tree/main/x/wasm/keeper"
    click RollupKeeper "https://github.com/airchains-network/junction/blob/main/x/rollup/module/module.go"
    click RollupIBC "https://github.com/airchains-network/junction/blob/main/x/rollup/module_ibc.go"
    click GRPC "https://github.com/airchains-network/junction/blob/main/api/junction/rollup/query_grpc.pb.go"

    classDef consensus fill:#add8e6,stroke:#000,stroke-width:1px
    classDef app fill:#98fb98,stroke:#000,stroke-width:1px
    classDef module fill:#90ee90,stroke:#000,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef api fill:#afeeee,stroke:#000,stroke-width:1px
    classDef client fill:#ffffe0,stroke:#000,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#000,stroke-width:1px
```
