# maushish/alris architecture

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

- Interactive diagram: https://gitdiagram.com/maushish/alris
- Repository: https://github.com/maushish/alris

## Overview

##### Project Type and Purpose
- Alris is an AI-driven yield optimizer and auto-trader built on the Solana blockchain. It’s a full-stack application that leverages Next.js for the UI/front-end and includes backend API endpoints for data fetching and on-chain interactions.
- Its main goals are to fetch real-time market data (via CoinGecko and Orca APIs), apply an AI-driven trading strategy (using GPTv4 and Grok XAI), and execute transactions with Solana (through the Solana Agent Kit).

##### File Structure
- Notice that the top-level is a combination of configuration files (e.g., next.config.ts, tailwind.config.ts, tsconfig.json) and the project’s core directories.
- The "src" folder contains:
- app – This indicates the usage of the new Next.js app directory that defines routes, layouts, and page components (e.g., dashboard and main pages).
- components/ui – This directory hosts modular UI components like alerts, buttons, cards, dialogs, etc.
- lib – Contains backend utility libraries, such as MongoDB connectivity (src/lib/mongodb.ts) and general utilities.
- pages/api – Houses API endpoints including those for CoinGecko, Crossmint, Orca, and waitlist functionalities, suggesting that the back end is responsible for interfacing with external APIs and possibly enabling interactions with the blockchain.
- Other directories like “models” and “types” hint that there is some domain modeling (e.g., waitlist-related models) and type definitions that ensure consistency throughout the project.

a. Main Components to Include:
- Frontend (Next.js app):
- Pages and layouts from src/app.
- UI Components from src/components/ui.
- Global styling (globals.css) and layout components.
- Backend/API Layer:
- API endpoints from src/pages/api for handling requests to external services such as CoinGecko, Orca, and Crossmint.
- Utility libraries found in src/lib, such as the MongoDB connection, suggest there’s internal state or user management (e.g., waitlist feature).
- External Services/Integrations:
- CoinGecko API: For fetching token price data.
- Orca API: For retrieving yield pool data.
- Solana Agent Kit: For executing on-chain transactions.
- Switchboard Oracle (mentioned in README): For pulling real-time data feeds.
- Grok XAI & GPTv4: For processing market data and generating AI-driven trading strategies.
b. Relationships and Interactions:
- Flow from the user interface (Next.js front end) sending user interactions or data requests to the backend API endpoints.
- The backend endpoints then communicate with external services to fetch market data, which is processed by the AI modules.
- Once a strategy is established, the transaction execution module triggers the Solana Agent Kit to perform the transfer or trade on-chain.
- Optionally, include the MongoDB (or other storage) that might log transactions or maintain a waitlist.
c. Architectural Patterns / Design Principles:
- Separation of concerns: Clearly differentiate between client side (UI/components) and server side (API endpoints and business logic).
- Modular design: Independent UI components, discrete API services, and isolated utility modules.
- Integration of external services via well-defined adapter APIs.
d. Technologies and Frameworks:
- Next.js for the web framework.
- Tailwind CSS for styling (tailwind.config.ts).
- Typescript across the project (tsconfig.json, .ts and .tsx files).
- MongoDB for data persistence (as seen in src/lib/mongodb.ts).
- External APIs (CoinGecko, Orca, etc.) and blockchain technologies specific to Solana.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        NextJS("Next.js App (Pages & Layouts)"):::frontend
        UIComponents("UI Components"):::frontend
        NextJS -->|"uses"| UIComponents
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API("API Endpoints"):::backend
        Utils("Utility Libraries"):::backend
        Models("Domain Models"):::backend
        Types("Type Definitions"):::backend
        UtilsTypes("Utils Types"):::backend
        API -->|"uses"| Utils
        API -->|"models"| Models
        API -->|"types"| Types
        Types -->|"includes"| UtilsTypes
    end

    %% External Integrations
    subgraph "External Integrations"
        CoinGecko("CoinGecko API"):::external
        Orca("Orca API"):::external
        Crossmint("Crossmint API"):::external
        Switchboard("Switchboard Oracle"):::external
        AIModule("AI Module (GPTv4 & Grok XAI)"):::external
        Solana("Solana Agent Kit"):::external
    end

    %% Inter-layer Connections
    NextJS -->|"calls"| API
    API -->|"fetchData"| CoinGecko
    API -->|"fetchData"| Orca
    API -->|"payment"| Crossmint
    API -->|"dataFeed"| Switchboard
    API -->|"processData"| AIModule
    AIModule -->|"executeTx"| Solana

    %% Click Events
    click NextJS "https://github.com/maushish/alris/tree/main/src/app"
    click UIComponents "https://github.com/maushish/alris/tree/main/src/components/ui"
    click API "https://github.com/maushish/alris/tree/main/src/pages/api"
    click Utils "https://github.com/maushish/alris/tree/main/src/lib"
    click Models "https://github.com/maushish/alris/tree/main/models"
    click Types "https://github.com/maushish/alris/tree/main/types"
    click UtilsTypes "https://github.com/maushish/alris/blob/main/src/utils/types.ts"

    %% Class Definitions for styling
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
```
