# wh00hw/zizza-backend architecture

> Architecture diagram of the GitHub repository wh00hw/zizza-backend, 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/wh00hw/zizza-backend
- Repository: https://github.com/wh00hw/zizza-backend

## Overview

##### Project Type & Purpose
- This is a backend server that exposes REST APIs to perform various cryptocurrency operations (e.g., setting up an agent, depositing funds, swapping assets, and withdrawals) on the NEAR and Zcash blockchains.
- It is designed as an API service and can be run as a standalone container via Docker or integrated as a Python package. The project also uses a submodule (zecwallet-light-cli) for interfacing with Zcash.

##### Main Components
- Client/Frontend:

- API Server:
– Represent the main server component that receives and processes API requests. This is implemented in server.py (likely using uvicorn for running the ASGI app) and exposes endpoints like /execute and /status/{task_id}.

- ZizZA Package Modules:
– API Module: The entry point for all operations (in zizza/api.py). This encapsulates methods like set_agent, get_wallet_summary, deposit, swap, withdraw, etc.
– Agent Module: Handles agent setup and initialization (found in zizza/agent.py).
– Middleware Module: Likely responsible for request processing and additional cross-cutting concerns (in zizza/middleware.py).

- Blockchain-specific Integrations:
– NEAR Components: Located within zizza/near, these modules (account.py, asset.py, intent_contract.py, nep413_signer.py, omni_bridge.py, solver.py, etc.) encapsulate functionalities specific to interfacing with the NEAR blockchain.
– Zcash Components: Located within zizza/zcash. Modules such as wallet.py interface with Zcash, and an external submodule (zecwallet-light-cli) provides deeper integration for Zcash wallet operations.

- Asynchronous Task Management:
– The server processes multiple operations asynchronously. Each batch of operations is associated with a unique task_id to track progress. Represent a “Task Queue” or “Task Manager” component handling this process flow.

##### Relationships and Interactions
- Request Flow:
– Show external clients making REST calls to the API Server.
– The API Server passes requests into the business logic encapsulated within the API module inside the ZizZA package.
- Internal Interactions:
– The API module delegates specific blockchain operations to either the NEAR or Zcash submodules.
– The NEAR and Zcash modules interact with blockchain-specific libraries and endpoints to execute operations like wallet initialization, checking balances, or performing asset swaps.
– The asynchronous task system tracks execution, and status queries (GET /status/{task_id}) are routed back to the API module for response construction.
- Submodule Integration:
– Represent the integration of the zecwallet-light-cli submodule under the Zcash component, showing that it is built separately (via Cargo) but integrated into the overall Zcash workflow.

##### Architectural Patterns & Technologies
- Modular Design: The separation into distinct directories (near, zcash, etc.) shows a clear modular approach.
- RESTful API Design: The server exposes multiple endpoints for CRUD-like operations and blockchain interactions.
- Asynchronous Processing: The use of asynchronous execution (via task IDs and parallel operations) is a fundamental design element.
- Containerization and Deployment: Usage of Dockerfile, .dockerignore indicates that containerization is a key part of deployment.
- Environment & Dependency Management: Virtual environments are provided via requirements.txt.
- Technology Stack:
- Python (core backend logic)
- Uvicorn (for running the ASGI application)
- Docker (for containerized deployments)
- Rust (for the Zcash wallet submodule via Cargo)

- Use Clear Labels: Each component (e.g., “API Server”, “NEAR Gateway”, “Zcash Wallet Integration”, “Task Manager”) should be clearly labeled.
- Layer the components logically: External Client at the top, followed by the API Server layer, then internal modules and integrations, and finally external blockchain networks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["External Client (Browser/Mobile)"]:::client

    %% API Server Layer
    API_Server["API Server (server.py)"]:::server

    %% API package layer
    API_Module["API Module (zizza/api.py)"]:::module
    Agent_Module["Agent Module (zizza/agent.py)"]:::module
    Middleware_Module["Middleware Module (zizza/middleware.py)"]:::module

    %% Task Manager for asynchronous operations
    Task_Manager["Task Manager (Async Operations)"]:::task

    %% Blockchain Integration Layers
    subgraph "Blockchain Integrations"
        NEAR_Components["NEAR Components (zizza/near/)"]:::module
        Zcash_Components["Zcash Components (zizza/zcash/)"]:::module
    end

    %% External Blockchains
    NEAR_Blockchain["NEAR Blockchain"]:::blockchain
    Zcash_Blockchain["Zcash Blockchain"]:::blockchain

    %% Connections
    Client -->|"REST API call"| API_Server
    API_Server -->|"Routes Request"| API_Module
    API_Module -->|"Handles Agent Setup"| Agent_Module
    API_Module -->|"Processes Middleware"| Middleware_Module
    API_Module -->|"Delegates to"| NEAR_Components
    API_Module -->|"Delegates to"| Zcash_Components
    API_Module -->|"Manages Tasks"| Task_Manager

    NEAR_Components -->|"Sends Requests"| NEAR_Blockchain
    Zcash_Components -->|"Sends Requests"| Zcash_Blockchain
    Task_Manager -->|"Status Updates"| API_Module

    %% Click Events
    click API_Server "https://github.com/wh00hw/zizza-backend/blob/master/server.py"
    click API_Module "https://github.com/wh00hw/zizza-backend/blob/master/zizza/api.py"
    click Agent_Module "https://github.com/wh00hw/zizza-backend/blob/master/zizza/agent.py"
    click Middleware_Module "https://github.com/wh00hw/zizza-backend/blob/master/zizza/middleware.py"
    click NEAR_Components "https://github.com/wh00hw/zizza-backend/tree/master/zizza/near/"
    click Zcash_Components "https://github.com/wh00hw/zizza-backend/tree/master/zizza/zcash/"

    %% Styles
    classDef client fill:#a1d99b,stroke:#333,stroke-width:2px;
    classDef server fill:#fc9272,stroke:#333,stroke-width:2px;
    classDef module fill:#9ecae1,stroke:#333,stroke-width:2px;
    classDef task fill:#fdae6b,stroke:#333,stroke-width:2px;
    classDef blockchain fill:#fdd0a2,stroke:#333,stroke-width:2px;
```
