# hash066/ai-agent-wallet-project architecture

> Architecture diagram of the GitHub repository hash066/ai-agent-wallet-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hash066/ai-agent-wallet-project
- Repository: https://github.com/hash066/ai-agent-wallet-project

## Overview

##### Project type and purpose
- This is a full-stack, blockchain-centric application that provides secure cross-chain intent execution for AI agents.
- It combines on-chain smart contracts (Sepolia + Polygon Amoy), off-chain microservices (relayer, watchdog, agent runtime, REST API), a React dashboard frontend, and monitoring/deployment infrastructure.

##### File structure
- Top-level directories:
- backend – REST API service, relayer, watchdog, agent runtime, local SQLite
- frontend – React/Vite dashboard
- load-tests – k6 scripts for performance
- monitoring – Prometheus + Alertmanager configs
- nginx – reverse-proxy ingress
- scripts – deploy.sh, Docker orchestration
- Deployment files: docker-compose.prod.yml, DEPLOYMENT.md
- Environment templates: .env.prod.example

##### README insights
- Off-chain flow: Agent Runtime → CrossChainExecutor (Sepolia) → Relayer → CrossChainExecutor (Amoy) → Watchdog → Token execution
- AuditLog and PolicyEngine enforce immutability and circuit breakers
- Frontend interacts with REST API for agent management, intents, audit trail, health & metrics

##### Elements
- Frontend/API – blue
- Infra (monitoring, ingress) – gray

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Presentation Layer"
        direction TB
        User(("User Browser")):::external
        Frontend["React/Vite Dashboard"]:::frontend
    end

    %% Off-Chain Services
    subgraph "Off-Chain Services"
        direction TB
        REST_API["REST API Backend"]:::frontend
        SQLite[(SQLite Database)]:::database
        Agent_Runtime["Agent Runtime Service"]:::offchain
        Relayer["Relayer Service"]:::offchain
        Watchdog["Watchdog Service"]:::offchain
    end

    %% On-Chain Sepolia Testnet
    subgraph "Sepolia Testnet" 
        direction TB
        AgentRegistry["AgentRegistry"]:::onchain
        AuditLog["AuditLog"]:::onchain
        PolicyEngine["PolicyEngine"]:::onchain
        SepoliaExecutor["CrossChainExecutor"]:::onchain
    end

    %% On-Chain Polygon Amoy
    subgraph "Polygon Amoy"
        direction TB
        PolyExecutor["CrossChainExecutor"]:::onchain
        Token["Test ERC-20 Token"]:::onchain
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Nginx["Nginx Ingress"]:::infra
        DockerCompose["Docker Compose Prod"]:::infra
        DeployScript["deploy.sh"]:::infra
        EnvTemplate[".env.prod.example"]:::infra
        DeploymentDoc["DEPLOYMENT.md"]:::infra
    end

    %% Monitoring Stack
    subgraph "Monitoring"
        direction TB
        Prometheus["Prometheus"]:::infra
        Alertmanager["Alertmanager"]:::infra
    end

    %% Load Testing
    LoadTests["Load-Testing (k6)"]:::external

    %% Connections - User Flow
    User -->|"1. interacts with"| Frontend
    Frontend -->|"2. API requests"| REST_API

    %% API to Sepolia
    REST_API -->|"3. ethers.js calls"| AgentRegistry
    REST_API -->|"3. ethers.js calls"| AuditLog
    REST_API -->|"3. ethers.js calls"| PolicyEngine
    REST_API -->|"3. ethers.js calls"| SepoliaExecutor

    %% Agent Runtime Intent Emission
    Agent_Runtime -->|"4. sign intent & call"| SepoliaExecutor

    %% Event -> Relayer -> Polygon
    SepoliaExecutor -->|"5. emits IntentEvent"| Relayer
    Relayer -->|"6. submits tx"| PolyExecutor

    %% Execution & Watchdog
    PolyExecutor -->|"7. timelock trigger"| Watchdog
    Watchdog -->|"7. verify/dispute"| PolyExecutor
    PolyExecutor -->|"7. execute"| Token

    %% Policy & Audit Enforcement
    AgentRegistry -->|"policy check"| SepoliaExecutor
    PolicyEngine -->|"circuit breaker"| SepoliaExecutor
    AuditLog -->|"record commitment"| SepoliaExecutor

    AgentRegistry -->|"policy check"| PolyExecutor
    PolicyEngine -->|"circuit breaker"| PolyExecutor
    AuditLog -->|"record commitment"| PolyExecutor

    %% Monitoring metrics
    REST_API -->|"metrics"| Prometheus
    Agent_Runtime -->|"metrics"| Prometheus
    Relayer -->|"metrics"| Prometheus
    Watchdog -->|"metrics"| Prometheus
    Prometheus -->|"alerts"| Alertmanager

    %% Infrastructure connections
    LoadTests -->|"load tests"| Nginx
    Nginx --> Frontend
    DockerCompose --> Nginx
    DockerCompose --> REST_API
    DockerCompose --> Agent_Runtime
    DockerCompose --> Relayer
    DockerCompose --> Watchdog
    DockerCompose --> Prometheus
    DockerCompose --> Alertmanager

    %% Database link
    REST_API -->|"reads/writes"| SQLite

    %% Click Events
    click REST_API "https://github.com/hash066/ai-agent-wallet-project/tree/main/backend/"
    click Agent_Runtime "https://github.com/hash066/ai-agent-wallet-project/tree/main/backend/"
    click Relayer "https://github.com/hash066/ai-agent-wallet-project/tree/main/backend/"
    click Watchdog "https://github.com/hash066/ai-agent-wallet-project/tree/main/backend/"
    click SQLite "https://github.com/hash066/ai-agent-wallet-project/tree/main/backend/"
    click Frontend "https://github.com/hash066/ai-agent-wallet-project/tree/main/frontend/"
    click LoadTests "https://github.com/hash066/ai-agent-wallet-project/blob/main/load-tests/k6-script.js"
    click Prometheus "https://github.com/hash066/ai-agent-wallet-project/blob/main/monitoring/prometheus.yml"
    click Alertmanager "https://github.com/hash066/ai-agent-wallet-project/blob/main/monitoring/alertmanager.yml"
    click Nginx "https://github.com/hash066/ai-agent-wallet-project/blob/main/nginx/nginx.conf"
    click DockerCompose "https://github.com/hash066/ai-agent-wallet-project/blob/main/docker-compose.prod.yml"
    click DeployScript "https://github.com/hash066/ai-agent-wallet-project/blob/main/scripts/deploy.sh"
    click EnvTemplate "https://github.com/hash066/ai-agent-wallet-project/blob/main/.env.prod.example"
    click DeploymentDoc "https://github.com/hash066/ai-agent-wallet-project/blob/main/DEPLOYMENT.md"

    %% Styles
    classDef onchain fill:#D8BFD8,stroke:#663399,color:#000
    classDef offchain fill:#98FB98,stroke:#228B22,color:#000
    classDef frontend fill:#ADD8E6,stroke:#1E90FF,color:#000
    classDef infra fill:#D3D3D3,stroke:#808080,color:#000
    classDef database fill:#FFE4B5,stroke:#DAA520,color:#000
    classDef external fill:#F5F5F5,stroke:#A9A9A9,color:#000
```
