# ask-the-hive/the-hive architecture

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

- Interactive diagram: https://gitdiagram.com/ask-the-hive/the-hive
- Repository: https://github.com/ask-the-hive/the-hive

## Overview

##### Main Components
- Frontend Application: Under the “app” and “components” directories, you have the Next.js UI including pages (e.g., token, portfolio, chat pages), reusable UI components, and custom hooks that manage state and perform queries.
- API Layer: Inside the “app/(app)/api” directory exists a variety of endpoints (for chat, tokens, portfolio, etc.) that serve as the backend for client calls. These endpoints route calls to business logic and services.
- AI Agent System: The “ai” folder houses an intricate agent framework. It’s organized into subdirectories for different agent types (market, liquidity, social, trading, wallet, etc.), plus separate modules for specialized actions (like “cdp”, “knowledge”, “solana”, “token-page”, “twitter”, etc.). This suggests an architecture where agents encapsulate specific business rules and automation tasks.
- Services & External Integrations: The “services” directory contains many integrations (Arkham, Birdeye, Dexscreener, Firecrawl, Helius, Hellomoon, Jupiter, Raydium, etc.). These are used by both API routes and agent actions to perform business-critical work through external systems.
- Database Layer: The “db” directory contains database container definitions, service logic, and type definitions for persisting chats, tokens, knowledge, etc.
- Utility and Shared Libraries: Additional functionality provided by the “hooks”, “lib”, and “types” folders supports cross-cutting concerns like client-side data fetching, wallet interactions, and static types.

##### Relationships and Interactions
- Frontend ⇄ API: The Next.js pages and UI components consume REST/edge API routes (e.g., for chat, token data, portfolio details).
- API ⇄ AI Agents: Many API endpoints are likely to trigger AI agent actions (found in “ai” and its subdirectories) that encapsulate smart business logic and domain-specific operations.
- API/Agents ⇄ Services: The agents and API routes rely on the services components to fetch external data, perform transactions, and interact with third-party platforms (like blockchain networks or social media APIs).
- API ⇄ Database: Data persistence operations occur via the “db” directories, enabling storage and retrieval of chats, token details, and other application data.
- UI ⇄ Hooks/Queries: The frontend leverages custom hooks (located under “hooks/queries” and “hooks/utils”) to manage client-side data synchronization with backend APIs.

##### Architectural Patterns and Design Principles
- Modular Design: Notice the clear separation into frontend, API, AI agents, services, and database layers.
- Microservice Integration: Although it’s a monorepo-style project, the “services” directory represents microservice-like adapters to external platforms.
- Agent-Based Logic: The various “ai/agents” directories indicate a design where domain-specific behaviors are encapsulated in agents (each with their capabilities, descriptions, names, and tools), which makes adding or updating functionalities more manageable.
- Clean Separation of Concerns: With dedicated folders for UI components, business logic (agents and services), and data handling (db), the project follows a well-defined separation of concerns.

##### Relevant Technologies
- Next.js (React) for the web UI and routing.
- TypeScript, as seen by the .ts and .tsx files throughout the project.
- External API integrations for blockchain (Solana, Raydium, etc.), analytics (Birdeye, Dexscreener), and social media (Twitter).
- Custom agent framework for “AI” functionality managing different token/market actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    user["User"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        ui_app["Next.js UI (app)"]:::ui
        ui_comp["UI Components (components)"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        api_ep["API Endpoints (app/(app)/api)"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        ai_agent["AI Agent Framework (ai)"]:::agent
    end

    %% External Integration Layer
    subgraph "External Integration"
        ext_services["External Services (services)"]:::service
    end

    %% Database Layer
    subgraph "Database Layer"
        db_node["Database (db)"]:::db
    end

    %% Utilities Layer
    subgraph "Utilities"
        hooks_node["Hooks (hooks)"]:::util
        lib_node["Lib (lib)"]:::util
        types_node["Types (types)"]:::util
    end

    %% Connections
    user --> ui_app
    user --> ui_comp

    ui_app -->|"consumes"| api_ep
    ui_comp -->|"consumes"| api_ep

    ui_app -->|"uses"| hooks_node
    ui_comp -->|"uses"| hooks_node
    ui_app -->|"uses"| lib_node
    ui_comp -->|"uses"| lib_node
    ui_app -->|"uses"| types_node
    ui_comp -->|"uses"| types_node

    api_ep -->|"triggers"| ai_agent
    api_ep -->|"persists"| db_node
    api_ep -->|"integrates"| ext_services
    ext_services -->|"responds"| api_ep

    ai_agent -->|"calls"| ext_services
    ai_agent -->|"updates"| db_node

    ext_services -->|"stores"| db_node

    %% Class Definitions for Styling
    classDef user fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef ui fill:#e3f2fd,stroke:#1976d2,stroke-width:2px;
    classDef api fill:#e8f5e9,stroke:#388e3c,stroke-width:2px;
    classDef agent fill:#fff8e1,stroke:#f57c00,stroke-width:2px;
    classDef service fill:#fce4ec,stroke:#d81b60,stroke-width:2px;
    classDef db fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
    classDef util fill:#ede7f6,stroke:#5c6bc0,stroke-width:2px;

    %% Click Events
    click ui_app "https://github.com/ask-the-hive/the-hive/tree/main/app/"
    click ui_comp "https://github.com/ask-the-hive/the-hive/tree/main/components/"
    click api_ep "https://github.com/ask-the-hive/the-hive/tree/main/app/(app)/api/"
    click ai_agent "https://github.com/ask-the-hive/the-hive/tree/main/ai/"
    click ext_services "https://github.com/ask-the-hive/the-hive/tree/main/services/"
    click db_node "https://github.com/ask-the-hive/the-hive/tree/main/db/"
    click hooks_node "https://github.com/ask-the-hive/the-hive/tree/main/hooks/"
    click lib_node "https://github.com/ask-the-hive/the-hive/tree/main/lib/"
    click types_node "https://github.com/ask-the-hive/the-hive/tree/main/types/"
```
