# daydreamsai/daydreams architecture

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

- Interactive diagram: https://gitdiagram.com/daydreamsai/daydreams
- Repository: https://github.com/daydreamsai/daydreams

## Overview

##### Main Components and Their Purpose

a. Core Engine and Libraries
- “packages” folder as the heart of the system. This folder includes multiple libraries such as:
– packages/core: Contains the main agent engine, context management, memory, task management, and multi-step reasoning logic.
– packages/cli: Implements the command-line interface for interacting with the core services.
– packages/create-agent: Provides templates and utilities for building new generative agents.
– packages/defai: Includes cross-chain transaction modules for blockchains like Ethereum, Solana, StarkNet, etc.
– Other packages (chroma, discord, hyperliquid, mongo, telegram, twitter) act as integration bridges or external service adapters.
- That these libraries implement the modular and pluggable architecture, enabling the system to interact with a variety of blockchain networks and APIs.

b. Client and User Interfaces
- Use the “clients/example-ui” directory to represent a sample front-end user interface. This layer shows how an end-user might interact with the agent framework.
- Components like the “agent” directory (agent/chat.ts, planner.ts, etc.), which handles client-specific agent logic and communication.
- Various UI components (e.g., app-sidebar, chat-sidebar, nav components) that build the user interface.

c. Documentation and Samples
- “docs” folder which includes the documentation site, sample layout files, and pages that explain how the framework works.
- The “examples” folder contains various illustrative usage cases (e.g., examples for chains, Discord interactions, server examples). Include these to show how different integration examples use and showcase the agent functionalities.

d. Infrastructure and Development Tools
- Existence of CI/CD workflows in the “.github/workflows” folder and build/deployment scripts in “scripts/” and “docker-compose.yaml”.
- Mention configuration files (.env.example, tsconfig.json, prettier configurations) that support the development process.

##### Depicting Relationships and Data Flows

- That the CLI (packages/cli) can serve as an alternate interface that invokes or orchestrates actions in the core engine.
- Flow from the “examples” directory into different integration points to illustrate how sample code interacts with both the UI and the core engine.

##### Architectural Patterns and Design Principles

- Clearly demonstrate the monorepo modular architecture using separate blocks for each major domain (Core, UI, Integration, Docs, and Examples).
- How separation of concerns is maintained through distinct packages—each dedicated to a specific integration or a specific layer (e.g., user-facing component versus backend logic).
- Extensibility: the design should illustrate how adding a new integration (say a new blockchain or an external API adapter) would simply mean adding a new package/module.
- Continuous integration/deployment flows by showing a side module (CI/CD workflows) that feeds into testing and building various packages.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Engine and Libraries
    subgraph "Core Engine and Libraries"
        Core["packages/core: Main agent engine, context management, memory, task management, and reasoning logic"]:::core
        CLI["packages/cli: Command-Line Interface"]:::core
        CreateAgent["packages/create-agent: Agent Template & Builder"]:::core
        Defai["packages/defai: Cross-chain Transaction Modules"]:::integration
        Discord["packages/discord: Integration Bridge – Discord"]:::integration
        Telegram["packages/telegram: Integration Bridge – Telegram"]:::integration
        Twitter["packages/twitter: Integration Bridge – Twitter"]:::integration
        Chroma["packages/chroma: Integration Bridge – Chroma"]:::integration
        Hyperliquid["packages/hyperliquid: Integration Bridge – Hyperliquid"]:::integration
        Mongo["packages/mongo: Integration Bridge – Mongo (Persistent Storage)"]:::integration
    end

    %% User Interfaces
    subgraph "User Interfaces"
        UI["clients/example-ui: Sample Front-end UI"]:::frontend
        AgentClient["clients/example-ui/src/agent: Agent Client Logic (chat.ts, planner.ts, etc.)"]:::frontend
    end

    %% Documentation and Samples
    subgraph "Documentation and Samples"
        Docs["docs: Documentation Site and Guides"]:::docs
        Examples["examples: Example Applications"]:::docs
    end

    %% Infrastructure and Dev Tools
    subgraph "Infrastructure & Dev Tools"
        CI[".github/workflows: CI/CD Workflows"]:::infra
        Scripts["scripts & docker-compose.yaml: Build/Deployment Scripts"]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        Blockchains["Blockchain Networks (Ethereum, Solana, StarkNet, etc.)"]:::external
        LLM["LLM Providers (OpenAI, Anthropic, Groq, Gemini)"]:::external
        APIs["External APIs & Services"]:::external
    end

    %% Relationships and Data Flow
    UI -->|"uses"| AgentClient
    AgentClient -->|"invokes"| Core
    CLI -->|"interfaces with"| Core

    Core -->|"calls"| Defai
    Core -->|"integrates with"| Discord
    Core -->|"integrates with"| Telegram
    Core -->|"integrates with"| Twitter
    Core -->|"optionally connects to"| Chroma
    Core -->|"optionally connects to"| Hyperliquid
    Core -->|"stores data to"| Mongo

    Defai -->|"interactsWith"| Blockchains
    Discord -->|"sendsDataTo"| APIs
    Telegram -->|"sendsDataTo"| APIs
    Twitter -->|"sendsDataTo"| APIs
    Chroma -->|"queries"| APIs
    Hyperliquid -->|"queries"| APIs
    Mongo -->|"maintains persistency for"| Core

    Examples -->|"demonstrates use of"| Core
    Examples -->|"demonstrates use of"| UI

    CI -->|"triggers builds for"| Core
    CI -->|"triggers builds for"| UI

    %% External communication from Core to External Systems
    Core -->|"fetches context from"| LLM

    %% Click Events
    click Core "https://github.com/daydreamsai/daydreams/tree/main/packages/core"
    click CLI "https://github.com/daydreamsai/daydreams/tree/main/packages/cli"
    click CreateAgent "https://github.com/daydreamsai/daydreams/tree/main/packages/create-agent"
    click Defai "https://github.com/daydreamsai/daydreams/tree/main/packages/defai"
    click Discord "https://github.com/daydreamsai/daydreams/tree/main/packages/discord"
    click Telegram "https://github.com/daydreamsai/daydreams/tree/main/packages/telegram"
    click Twitter "https://github.com/daydreamsai/daydreams/tree/main/packages/twitter"
    click Chroma "https://github.com/daydreamsai/daydreams/tree/main/packages/chroma"
    click Hyperliquid "https://github.com/daydreamsai/daydreams/tree/main/packages/hyperliquid"
    click Mongo "https://github.com/daydreamsai/daydreams/tree/main/packages/mongo"
    click UI "https://github.com/daydreamsai/daydreams/tree/main/clients/example-ui"
    click AgentClient "https://github.com/daydreamsai/daydreams/tree/main/clients/example-ui/src/agent"
    click Docs "https://github.com/daydreamsai/daydreams/tree/main/docs"
    click Examples "https://github.com/daydreamsai/daydreams/tree/main/examples"
    click CI "https://github.com/daydreamsai/daydreams/tree/main/.github/workflows"
    click Scripts "https://github.com/daydreamsai/daydreams/tree/main/scripts"

    %% Styles
    classDef core fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef integration fill:#aed6f1,stroke:#154360,stroke-width:2px;
    classDef frontend fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef docs fill:#f5cba7,stroke:#7d3c98,stroke-width:2px;
    classDef infra fill:#d2b4de,stroke:#6c3483,stroke-width:2px;
    classDef external fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
```
