# omsant02/3sips architecture

> Architecture diagram of the GitHub repository omsant02/3sips, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omsant02/3sips
- Repository: https://github.com/omsant02/3sips

## Overview

##### Project Type and Purpose
- This is a full-stack, blockchain-centric application combining:
- A Node.js/TypeScript AI agent (sip-agent)
- A React/Web3 frontend
- On-chain smart contracts (in the top-level contracts folder)
- Purpose: Provide an autonomous AI-driven, cross-chain crypto investment platform (3SIPS) that leverages ElizaOS for natural-language interaction, Chainlink Automation for scheduled actions, and Avalanche subnets for fund distribution.

##### File-Structure Analysis
- Top level
- contracts/ → Solidity smart contracts (ERC20 token, home & remote contracts).
- sip-agent/ → Agent service & frontend mono-repo managed by Bun & Vite.
- sip-agent/src
- frontend/ → React UI (index.tsx, index.html, styles)
- actions/ → Business logic for SIP operations
- services/web3Service.ts → Blockchain interaction via ethers.js
- index.ts & plugin.ts → Agent entrypoints and plugin scaffolding
- types/contracts.ts → TypeScript interfaces for on-chain contracts
- Config & scripts
- bunfig.toml, tsconfig.json, vite.config.ts, tsup.config.ts → Build and dev toolchain
- scripts/ */test-all.sh, install-test-deps.js → CI and test orchestration
- Tests
- __tests__/unit, integration, e2e & Cypress component/e2e tests cover UI and agent logic.

##### README Insights
- Architecture section shows high-level flow:
User → ElizaOS AI Agent → Chainlink Automation → Smart Contracts → Multi-Chain Distribution
- Describes three Avalanche subnets: Fuji (30%), Echo (60%), Dispatch (10%)
- Technical stack: ElizaOS, Chainlink, Avalanche ICTT, Solidity, Node.js/TypeScript, React, ethers.js

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User["User"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UI_index["index.tsx"]:::frontend
        UI_html["index.html"]:::frontend
        UI_css["index.css"]:::frontend
        UI_utils["utils.ts"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Agent_index["index.ts"]:::agent
        Agent_plugin["plugin.ts"]:::agent
        Agent_character["character.ts"]:::agent
        SIP_actions["sipActions.ts"]:::agent
        Web3_service["web3Service.ts"]:::agent
        Types_contracts["contracts.ts"]:::agent
    end

    %% Persistence / Execution Layer
    subgraph "Persistence / Execution Layer"
        direction TB
        Smart_contracts["Smart Contracts (contracts/)"]:::onchain
        subgraph "Avalanche Subnets"
            direction TB
            Fuji["Fuji (30%)"]:::onchain
            Echo["Echo (60%)"]:::onchain
            Dispatch["Dispatch (10%)"]:::onchain
        end
    end

    %% External Services
    subgraph "External Integrations"
        direction TB
        ElizaOS["ElizaOS (AI/NLP)"]:::external
        Chainlink["Chainlink Automation"]:::external
    end

    %% Configuration & CI/Build
    subgraph "Config & Build Toolchain"
        direction TB
        Bunfig["bunfig.toml"]:::config
        TSconfig["tsconfig.json<br/>tsconfig.build.json"]:::config
        Vite_config["vite.config.ts"]:::config
        Tsup_config["tsup.config.ts"]:::config
    end

    subgraph "CI & Test Orchestration"
        direction TB
        Scripts_testall["test-all.sh"]:::test
        Scripts_install["install-test-deps.js"]:::test
    end

    subgraph "Testing Harnesses"
        direction TB
        Unit_tests["Unit & Integration Tests<br/>(src/__tests__)"]:::test
        Cypress_tests["Cypress Specs<br/>(src/__tests__/cypress)"]:::test
    end

    %% Connections
    User -->|"issues commands"| UI_index
    UI_index -->|"imports & calls"| Agent_index
    UI_html --> Agent_index
    UI_css --> Agent_index
    UI_utils --> Agent_index

    Agent_index -->|"loads plugin"| Agent_plugin
    Agent_index -->|"defines character"| Agent_character
    Agent_index -->|"executes workflows"| SIP_actions
    Agent_index -->|"calls blockchain"| Web3_service
    Agent_index -->|"uses types"| Types_contracts

    Agent_index -->|"uses"| ElizaOS
    Agent_index -->|"registers tasks"| Chainlink
    Agent_index -->|"direct calls"| Smart_contracts

    Smart_contracts -->|"distribute funds"| Fuji
    Smart_contracts -->|"distribute funds"| Echo
    Smart_contracts -->|"distribute funds"| Dispatch

    Smart_contracts -->|"events"| Agent_index
    Agent_index -->|"updates UI"| UI_index

    %% Build & Config links
    Agent_index --> Bunfig
    Agent_index --> TSconfig
    Agent_index --> Vite_config
    Agent_index --> Tsup_config

    Agent_index --> Scripts_testall
    Agent_index --> Scripts_install

    Agent_index --> Unit_tests
    Agent_index --> Cypress_tests

    %% Click Events
    click UI_index "https://github.com/omsant02/3sips/blob/main/sip-agent/src/frontend/index.tsx"
    click UI_html "https://github.com/omsant02/3sips/blob/main/sip-agent/src/frontend/index.html"
    click UI_css "https://github.com/omsant02/3sips/blob/main/sip-agent/src/frontend/index.css"
    click UI_utils "https://github.com/omsant02/3sips/blob/main/sip-agent/src/frontend/utils.ts"
    click Agent_index "https://github.com/omsant02/3sips/blob/main/sip-agent/src/index.ts"
    click Agent_plugin "https://github.com/omsant02/3sips/blob/main/sip-agent/src/plugin.ts"
    click Agent_character "https://github.com/omsant02/3sips/blob/main/sip-agent/src/character.ts"
    click SIP_actions "https://github.com/omsant02/3sips/blob/main/sip-agent/src/actions/sipActions.ts"
    click Web3_service "https://github.com/omsant02/3sips/blob/main/sip-agent/src/services/web3Service.ts"
    click Types_contracts "https://github.com/omsant02/3sips/blob/main/sip-agent/src/types/contracts.ts"
    click Smart_contracts "https://github.com/omsant02/3sips/tree/main/contracts/"
    click Bunfig "https://github.com/omsant02/3sips/blob/main/sip-agent/bunfig.toml"
    click TSconfig "https://github.com/omsant02/3sips/blob/main/sip-agent/tsconfig.json"
    click Vite_config "https://github.com/omsant02/3sips/blob/main/sip-agent/vite.config.ts"
    click Tsup_config "https://github.com/omsant02/3sips/blob/main/sip-agent/tsup.config.ts"
    click Scripts_testall "https://github.com/omsant02/3sips/blob/main/sip-agent/scripts/test-all.sh"
    click Scripts_install "https://github.com/omsant02/3sips/blob/main/sip-agent/scripts/install-test-deps.js"
    click Unit_tests "https://github.com/omsant02/3sips/tree/main/sip-agent/src/__tests__"
    click Cypress_tests "https://github.com/omsant02/3sips/tree/main/sip-agent/src/__tests__/cypress"

    %% Styles
    classDef frontend fill:#ffcc00,stroke:#333,stroke-width:1px
    classDef agent fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef onchain fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef config fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef test fill:#f9f9f9,stroke:#333,stroke-width:1px
```
