# 0xkar4n/aptosone architecture

> Architecture diagram of the GitHub repository 0xkar4n/aptosone, 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/0xkar4n/aptosone
- Repository: https://github.com/0xkar4n/aptosone

## Overview

##### Project Type and Purpose
- Project Type: This is a full-stack DeFi platform built on the Aptos blockchain with additional integrations for AI-powered yield strategies and a Discord bot.
- Primary Purpose: Provide users with wallet creation/management, staking/unstaking operations, access to lending/borrowing pools (via Joule Finance integration), AI strategy recommendations, and interaction via both a web app and a Discord bot.

##### File Structure
- Frontend and API Routes:
- The “app” directory contains all the Next.js pages, API endpoints (in subfolders like /api, /app, and nested routes) and global configuration/layout files.
- API routes exist for various functionalities (e.g., agent, ai-strategy, chat, and wallet operations) which implies that many operations are exposed as HTTP endpoints.
- UI Components:
- The “components” folder holds a diverse set of React components, including both the main UI components (e.g., WalletProvider, ChatWidget, StakingCard) and specialized landing page components.
- Custom Tools:
- The “custom-tools” directory contains scripts for executing strategies (e.g., joule-ai-strategy, joule-top-borrow-pool), indicating integration with external services (like Joule Finance).
- Discord Bot:
- The “discord-bot” folder represents a distinct microservice structured as a Node.js project, complete with its own Prisma schema/migrations and source code.
- Shared Libraries & Utilities:
- The “lib” and “utils” directories include helper scripts and utilities for blockchain interaction (e.g., aptosAgent, fetchAptosOneWallet), cryptography, and handling data.

##### Architectural Components
a. Client (Frontend) Layer:
- Next.js Web App UI: This includes pages for wallet creation, staking, positions, AI strategy display, and interactions.
- Components: Visual elements for navigation (e.g., landing pages, navbar, footer) and functional components (e.g., ChatWidget, StakingCards).
b. API / Backend Layer:
- Next.js API Endpoints: A set of RESTful or similar endpoints handling wallet actions, chat interactions, strategy executions, and position management.
- Utility and Helper Functions: Wrap third‐party integrations (Aptos SDK, Move-Agent Kit) and internal logic.
c. Discord Bot Service:
- A separate microservice that is likely interfacing with the same underlying database or backend logic. It leverages Prisma for database operations and uses Move-Agent Kit tools for executing DeFi operations via Discord commands.
d. Database:
- PostgreSQL accessed via Prisma ORM is central to persisting user information, wallet details, staking data, etc.
e. External Services/Integrations:
- Aptos Blockchain: Via the Aptos SDK and Move-Agent Kit for wallet and transaction functionality.
- Joule Finance: For lending and borrowing pools, integrated through custom tools.
- AI Strategy Services: Likely tied to the prompts originated from the UI and processed as part of the strategy endpoints.

##### Relationships and Data Flow
- Users interact with the Web UI (client) → triggers API calls (Next.js API endpoints).
- API endpoints process data using shared utilities and custom tools, making calls to the Aptos blockchain (for wallet management and transactions) and connecting to external services (Joule Finance, AI strategy processing).
- The backend services persist necessary data in the PostgreSQL database (via Prisma) that is also accessed by the separate Discord bot service.
- The Discord Bot (as a separate service) handles user interactions in Discord, which might in turn trigger similar database operations and blockchain interactions.

##### Architectural Patterns/Design Principles
- Separation of Concerns: The architecture clearly segregates the frontend (UI components and pages), backend API endpoints, business logic (custom tools and utilities), and external integrations.
- Microservices: The Discord bot exists as a separate microservice and might eventually be expanded out of the main codebase.
- MVC-Like Structure: While it uses Next.js which blends views and API routes, the structure clearly distinguishes view layers from functional API endpoints.
- Modular Design: With separate directories for API routes, components, utilities, and custom tools, each module has a clean responsibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        A["Next.js Web App UI"]:::frontend
        B["UI Components"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        C["API Endpoints"]:::backend
        D["Custom Tools"]:::backend
        E["Discord Bot Service"]:::microservice
        F["Shared Libraries & Utilities"]:::utility
    end

    %% Data Layer
    subgraph "Data Layer"
        G["PostgreSQL Database"]:::database
    end

    %% External Services Layer
    subgraph "External Services"
        H["Aptos Blockchain"]:::external
        I["Joule Finance Integration"]:::external
        J["AI Strategy Engine"]:::external
    end

    %% Data Flows
    A -->|"HTTP"| C
    A -->|"renders"| B
    C -->|"CRUD"| G
    C -->|"BlockchainTX"| H
    C -->|"Integration"| I
    C -->|"AIcalls"| J
    C ---|"uses"| F
    E -->|"DBAccess"| G
    E -->|"BlockchainTX"| H
    E -->|"Integration"| I
    E -->|"AIcalls"| J
    E ---|"uses"| F
    D -->|"Executes"| I
    D -->|"BlockchainTX"| H
    D -->|"AIrecos"| J
    F ---|"helpers"| C
    F ---|"helpers"| E

    %% Styles for layers & components
    classDef frontend fill:#a3d8f4,stroke:#036,stroke-width:2px;
    classDef backend fill:#b3e6b3,stroke:#363,stroke-width:2px;
    classDef microservice fill:#f9d6a5,stroke:#c65,stroke-width:2px;
    classDef utility fill:#d3bde0,stroke:#935,stroke-width:2px;
    classDef database fill:#ffe6a7,stroke:#ab7,stroke-width:2px;
    classDef external fill:#f4b3a3,stroke:#933,stroke-width:2px;

    %% Click Events
    click A "https://github.com/0xkar4n/aptosone/tree/main/app/app"
    click C "https://github.com/0xkar4n/aptosone/tree/main/app/api"
    click B "https://github.com/0xkar4n/aptosone/tree/main/components"
    click D "https://github.com/0xkar4n/aptosone/tree/main/custom-tools"
    click E "https://github.com/0xkar4n/aptosone/tree/main/discord-bot"
    click F "https://github.com/0xkar4n/aptosone/tree/main/lib"
    click F "https://github.com/0xkar4n/aptosone/tree/main/utils"
    click G "https://github.com/0xkar4n/aptosone/tree/main/prisma"
```
