# ahmadnurfadilah/aptomizer architecture

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

- Interactive diagram: https://gitdiagram.com/ahmadnurfadilah/aptomizer
- Repository: https://github.com/ahmadnurfadilah/aptomizer

## Overview

##### Project Type and Purpose
- Aptomizer is a full-stack AI-powered portfolio management and optimization tool for the Aptos blockchain.
- It integrates a chatbot AI assistant (using OpenAI and Vercel AI SDK) with blockchain interactions (via the Aptos SDK and Move Agent Kit), portfolio analytics, yield opportunities, and wallet management.
- The application leverages modern front-end tools (Next.js 15 with the App Router, Tailwind CSS, Shadcn UI, and Radix UI) combined with back-end API endpoints, Prisma-based database interaction (using PostgreSQL via Supabase), and custom blockchain libraries.

##### High-Level Architectural Components
a. Frontend (Client Side):
- Pages and Layouts: Found mainly under the app/ folder (app/page.tsx, app/dashboard/page.tsx, app/profile/page.tsx, etc.).
- UI Components: Custom React components under components/ (various UI widgets like buttons, charts, chat inputs, dashboards, onboarding flows, and wallet selectors).
- Global Styles: The global stylesheet (app/globals.css) and theming components (components/theme-provider.tsx).

b. API Endpoints (Backend API Layer):
- Located in app/api/ directory, segregated by functionalities:
- Chat endpoints (app/api/chat/route.ts): For interacting with the AI assistant.
- User-related endpoints (e.g., create, generate-ai-wallet, portfolio, profile, risk profile update/save, etc.).
- These endpoints handle user requests, communicate with the blockchain libraries, and facilitate AI conversations.

c. Business Logic & Blockchain Integration (Service Layer):
- Libraries in the lib/ directory provide core functions:
- Blockchain operations for Aptos, Panora, and related financial functionalities (found under lib/tools/aptos, lib/tools/joule, lib/tools/panora).
- Utility functions for portfolio analysis (like lib/clean-joule-all-positions-list.ts, lib/get-pool-address-by-token-name.ts).
- Wallet service integration to handle wallet interactions and security.
- Prisma database integration (lib/prisma.ts) interacts with the PostgreSQL database configured in prisma/schema.prisma.

d. Database:
- Managed via Prisma and PostgreSQL (with schema file located in prisma/schema.prisma). This layer stores user data, portfolio snapshots, risk profiles, and possibly transaction logs.

##### Relationships and Data Flow
- User interacts with the Frontend UI (via Next.js application components).
- Frontend sends requests to API endpoints (HTTP/REST style) for operations like chatting with the AI assistant, wallet creation, portfolio analysis, and transaction execution.
- API endpoints delegate heavy lifting to service layer functions in the lib directory. This includes blockchain queries (getting token details, fetching balances, transferring tokens/NFTs), and yield opportunities.
- Data from the blockchain and user actions is persisted and queried via the Prisma client and the database.
- External APIs (OpenAI API, Aptos blockchain endpoints, Panora API) are interfaced by the service layer functions.

##### Important Architectural Patterns and Technologies
- Separation of Concerns: Clear distinction between UI (view layer), API endpoints (controller layer), and service libraries (business logic layer).
- Modular Design: Code is organized into self-contained modules (e.g. separate directories for chat, profile, optimization in API, and blockchain operations in lib/tools).
- API Gateway-like Behavior: The Next.js API routes serve as gatekeepers, handling communication between the frontend and backend services.
- Security: Special attention is given to private key handling and encryption via environment variables and secure configurations.
- Use of Modern Tools: Next.js 15 with the App Router for a modern, file-system-based routing; Prisma for ORM; Vercel AI SDK and OpenAI API for enhanced AI functionalities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Node
    U("User"):::user

    %% Frontend Subgraph
    subgraph "Frontend UI"
        subgraph "Pages and Layouts"
            home["Home Page"]:::frontend
            dashboard["Dashboard"]:::frontend
            profilePage["Profile Page"]:::frontend
            globals["Global Styles"]:::frontend
            layout["App Layout"]:::frontend
        end
        subgraph "UI Components & Theming"
            themeProvider["Theme Provider"]:::frontend
            walletSelector["Wallet Selector"]:::frontend
            uiComponents["UI Widgets"]:::frontend
        end
    end

    %% API Endpoints Subgraph
    subgraph "API Endpoints"
        chatEP["Chat Endpoint"]:::api
        createEP["User Create"]:::api
        genAIWalletEP["Generate AI Wallet"]:::api
        hasAIWalletEP["Has AI Wallet"]:::api
        optEP["Optimization"]:::api
        portEP["Portfolio"]:::api
        profileEP["Profile"]:::api
        saveRiskEP["Save Risk Profile"]:::api
        updateProfileEP["Update Profile"]:::api
        updateRiskEP["Update Risk Profile"]:::api
    end

    %% Service & Blockchain Subgraph
    subgraph "Service Layer & Blockchain"
        %% Utilities Group
        subgraph "Utilities"
            utilities1["Clean Joule Positions"]:::service
            utilities2["Get Pool Address"]:::service
            utilities3["Utils"]:::service
        end
        %% Prisma and Database Integration Group
        subgraph "Prisma & Database Integration"
            prismaClient["Prisma Client"]:::service
            dbSchema["DB Schema"]:::service
        end
        aptosOperations["Aptos Operations"]:::service
        jouleOperations["Joule Operations"]:::service
        panoraOperations["Panora Operations"]:::service
        walletService["Wallet Service"]:::service
    end

    %% Database Node
    databaseDB(("Database (Prisma/PostgreSQL)")):::database

    %% External Integrations Subgraph
    subgraph "External Integrations"
        openAI["OpenAI / Vercel AI"]:::external
        blockchainNodes["Blockchain Nodes"]:::external
    end

    %% Connections from User to Frontend
    U -->|"interacts"| home
    U -->|"interacts"| dashboard
    U -->|"interacts"| profilePage

    %% Connections from Frontend to API Endpoints
    home -->|"sends request"| chatEP
    walletSelector -->|"wallet action"| genAIWalletEP

    %% API Endpoints to Service/External
    chatEP -->|"chat request"| openAI
    createEP -->|"create user"| prismaClient
    genAIWalletEP -->|"wallet creation"| walletService
    hasAIWalletEP -->|"check wallet"| walletService
    optEP -->|"optimization"| aptosOperations
    portEP -->|"portfolio analysis"| jouleOperations
    profileEP -->|"profile fetch"| prismaClient
    saveRiskEP -->|"save risk"| prismaClient
    updateProfileEP -->|"update profile"| prismaClient
    updateRiskEP -->|"update risk"| prismaClient

    %% Connections within Service Layer to Database
    prismaClient -->|"persist data"| databaseDB
    prismaClient -->|"sync with"| dbSchema

    %% Service Layer to External Integrations
    aptosOperations -->|"blockchain query"| blockchainNodes
    jouleOperations -->|"pool data"| blockchainNodes
    panoraOperations -->|"swap operation"| blockchainNodes
    walletService -->|"wallet txn"| blockchainNodes

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef service fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef database fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef user fill:#fdebd0,stroke:#d35400,stroke-width:2px;

    %% Click Events for Frontend UI
    click home "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/page.tsx"
    click dashboard "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/dashboard/page.tsx"
    click profilePage "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/profile/page.tsx"
    click globals "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/globals.css"
    click layout "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/layout.tsx"
    click themeProvider "https://github.com/ahmadnurfadilah/aptomizer/blob/main/components/theme-provider.tsx"
    click walletSelector "https://github.com/ahmadnurfadilah/aptomizer/blob/main/components/wallet-selector.tsx"
    click uiComponents "https://github.com/ahmadnurfadilah/aptomizer/tree/main/components/ui/"

    %% Click Events for API Endpoints
    click chatEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/chat/route.ts"
    click createEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/user/create/route.ts"
    click genAIWalletEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/user/generate-ai-wallet/route.ts"
    click hasAIWalletEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/user/has-ai-wallet/route.ts"
    click optEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/user/optimization/route.ts"
    click portEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/user/portfolio/route.ts"
    click profileEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/user/profile/route.ts"
    click saveRiskEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/user/save-risk-profile/route.ts"
    click updateProfileEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/user/update-profile/route.ts"
    click updateRiskEP "https://github.com/ahmadnurfadilah/aptomizer/blob/main/app/api/user/update-risk-profile/route.ts"

    %% Click Events for Service Layer & Blockchain
    click utilities1 "https://github.com/ahmadnurfadilah/aptomizer/blob/main/lib/clean-joule-all-positions-list.ts"
    click utilities2 "https://github.com/ahmadnurfadilah/aptomizer/blob/main/lib/get-pool-address-by-token-name.ts"
    click utilities3 "https://github.com/ahmadnurfadilah/aptomizer/blob/main/lib/utils.ts"
    click prismaClient "https://github.com/ahmadnurfadilah/aptomizer/blob/main/lib/prisma.ts"
    click dbSchema "https://github.com/ahmadnurfadilah/aptomizer/blob/main/prisma/schema.prisma"
    click aptosOperations "https://github.com/ahmadnurfadilah/aptomizer/tree/main/lib/tools/aptos"
    click jouleOperations "https://github.com/ahmadnurfadilah/aptomizer/tree/main/lib/tools/joule"
    click panoraOperations "https://github.com/ahmadnurfadilah/aptomizer/blob/main/lib/tools/panora/swap.ts"
    click walletService "https://github.com/ahmadnurfadilah/aptomizer/blob/main/lib/wallet-service.ts"
```
