# growly-foundation/suite architecture

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

- Interactive diagram: https://gitdiagram.com/growly-foundation/suite
- Repository: https://github.com/growly-foundation/suite

## Overview

##### Project type and purpose
- This is a full-stack monorepo for an AI-powered DeFi “Suite”:
- Frontends: marketing site, admin dashboard, embeddable chat widget, playground
- Shared libraries: core utilities, UI components
- Backend: NestJS micro-service exposing AI/chat/agent APIs and on-chain integrations
- Purpose: let dApp builders embed an LLM-driven chat widget that guides users through DeFi workflows, managed via an admin dashboard, powered by a specialized multi-agent backend.

##### File structure
- Root: pnpm/Turbo monorepo orchestrates packages, workflows, Docker, CI/CD
- packages/core & packages/ui: shared code (models, services, components)
- packages/suite: React/TS “chat widget” library for embedding in dApps
- packages/dashboard, website, playground: Next.js frontends (admin, marketing, demo)
- packages/server: NestJS backend, modularized by feature (agent, chat, message, openai, suite-core, growly, firecrawl), interacts with a SQL database & external APIs
- Configs: Dockerfiles, docker-compose, GitHub Actions, Turborepo (turbo.json)

##### README for additional insights
- Client layers (Suite widget, Dashboard)
- NestJS server wrapping a Langchain multi-agent supervisor
- Specialized agents: Web3 Data Agent, Search Agent, Growly Agent
- Database for state, docs, workflow definitions
- External services: Firecrawl, DefiLlama, Tavily, Ponder (planned), OpenAI, x402 payments
- Tech stack: React/TS, Tailwind, Node/NestJS, Langchain, Onchainkit/Wagmi/Viem

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Shared Libraries
  subgraph "Shared Libraries"
    direction TB
    Core["@growly/core"]:::shared
    UI["@growly/ui"]:::shared
  end

  %% Frontends
  subgraph "Frontends"
    direction TB
    Website["Marketing Website"]:::frontend
    Dashboard["Admin Dashboard"]:::frontend
    SuiteWidget["Embeddable Chat Widget"]:::frontend
    Playground["Playground (Demo)"]:::frontend
  end

  %% Backend
  subgraph "Backend (NestJS)"
    direction TB
    AppRoot["NestJS App"]:::backend
    X402Middleware["x402 Redirect Middleware"]:::backend
    AgentSupervisor["Langchain Multi-Agent Supervisor"]:::backend
    ChatModule["Chat Module"]:::backend
    MessageModule["Message Module"]:::backend
    SuiteCoreModule["Suite-Core Module"]:::backend
    OpenAIModule["OpenAI Integration"]:::backend
    FirecrawlModule["Firecrawl Service"]:::backend
    DBService["Database Service"]:::backend
    AgentUtils["On-chain Utilities"]:::backend

    AppRoot -->|uses middleware| X402Middleware
    AppRoot -->|orchestrates| AgentSupervisor
    AppRoot -->|handles chat| ChatModule
    AppRoot -->|handles messages| MessageModule
    AppRoot -->|executes workflows| SuiteCoreModule
    AppRoot -->|provides| DBService

    AgentSupervisor -->|manages| Web3DataAgent
    AgentSupervisor -->|manages| SearchAgent
    AgentSupervisor -->|manages| OtherAgents

    ChatModule -->|calls| OpenAIModule
    ChatModule -->|delegates| AgentSupervisor

    MessageModule -->|persists| DBService
    SuiteCoreModule -->|persists| DBService

    OpenAIModule -->|LLM call| OpenAI
    FirecrawlModule -->|API call| FirecrawlExt

    Web3DataAgent["Growly Agent (Web3 Data)"]:::backend
    SearchAgent["Search Agent"]:::backend
    OtherAgents["Tavily & Zerion Agents"]:::backend

    Web3DataAgent -->|uses utils| AgentUtils
    AgentUtils -->|sends tx| Blockchain

    SearchAgent -->|calls| FirecrawlExt
    SearchAgent -->|calls| DefiLlama

    OtherAgents -->|calls| Tavily
    OtherAgents -->|calls| Zerion
  end

  %% Database
  DB["PostgreSQL Database"]:::db

  %% External Services
  subgraph "External Services"
    direction TB
    OpenAI["OpenAI"]:::external
    FirecrawlExt["Firecrawl API"]:::external
    DefiLlama["DefiLlama API"]:::external
    Tavily["Tavily API"]:::external
    Zerion["Zerion API"]:::external
    Ponder["Ponder (planned)"]:::external
    x402Payment["x402 Payments"]:::external
    Blockchain["Blockchain Networks"]:::external
  end

  %% Shared libs usage
  Core --> Website
  Core --> Dashboard
  Core --> SuiteWidget
  Core --> Playground
  UI --> Website
  UI --> Dashboard
  UI --> SuiteWidget
  UI --> Playground

  %% Frontend to Backend
  SuiteWidget -->|REST/WebSocket| AppRoot
  Dashboard -->|REST API| AppRoot

  %% Backend to External & DB
  DBService -->|SQL queries| DB
  X402Middleware -->|redirect| x402Payment

  %% Click Events
  click Core "https://github.com/growly-foundation/suite/tree/main/packages/core"
  click UI "https://github.com/growly-foundation/suite/tree/main/packages/ui"
  click Website "https://github.com/growly-foundation/suite/tree/main/packages/website"
  click Dashboard "https://github.com/growly-foundation/suite/tree/main/packages/dashboard"
  click SuiteWidget "https://github.com/growly-foundation/suite/tree/main/packages/suite"
  click Playground "https://github.com/growly-foundation/suite/tree/main/packages/playground"
  click AppRoot "https://github.com/growly-foundation/suite/blob/main/packages/server/src/main.ts"
  click AppRoot "https://github.com/growly-foundation/suite/blob/main/packages/server/src/app.module.ts"
  click AgentSupervisor "https://github.com/growly-foundation/suite/blob/main/packages/server/src/agent/agent.module.ts"
  click AgentSupervisor "https://github.com/growly-foundation/suite/blob/main/packages/server/src/agent/agent.service.ts"
  click Web3DataAgent "https://github.com/growly-foundation/suite/tree/main/packages/server/src/agent/tools/growly"
  click FirecrawlExt "https://github.com/growly-foundation/suite/blob/main/packages/server/src/agent/tools/firecrawl/firecrawl.ts"
  click DefiLlama "https://github.com/growly-foundation/suite/tree/main/packages/server/src/agent/tools/defillama"
  click Tavily "https://github.com/growly-foundation/suite/blob/main/packages/server/src/agent/tools/tavily.ts"
  click OtherAgents "https://github.com/growly-foundation/suite/tree/main/packages/server/src/agent/tools/zerion"
  click ChatModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/chat/chat.controller.ts"
  click ChatModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/chat/chat.service.ts"
  click MessageModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/message/message.module.ts"
  click MessageModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/message/message.repository.ts"
  click MessageModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/message/message.service.ts"
  click SuiteCoreModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/suite-core/suite-core.module.ts"
  click SuiteCoreModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/suite-core/suite-core.service.ts"
  click OpenAIModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/openai/openai.module.ts"
  click OpenAIModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/openai/openai.provider.ts"
  click FirecrawlModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/firecrawl/firecrawl.module.ts"
  click FirecrawlModule "https://github.com/growly-foundation/suite/blob/main/packages/server/src/firecrawl/firecrawl.service.ts"
  click DBService "https://github.com/growly-foundation/suite/blob/main/packages/server/src/databases/database.module.ts"
  click DBService "https://github.com/growly-foundation/suite/blob/main/packages/server/src/databases/suite.provider.ts"
  click X402Middleware "https://github.com/growly-foundation/suite/blob/main/packages/server/src/middleware/x402-redirect.middleware.ts"
  click AgentUtils "https://github.com/growly-foundation/suite/blob/main/packages/server/src/agent/utils/agent.factory.ts"
  click AgentUtils "https://github.com/growly-foundation/suite/blob/main/packages/server/src/agent/utils/model.factory.ts"
  click AgentUtils "https://github.com/growly-foundation/suite/blob/main/packages/server/src/agent/utils/checkpointer.ts"

  %% Styles
  classDef frontend fill:#B3D4FC,stroke:#0366D6,color:#000;
  classDef shared fill:#D6F7D6,stroke:#2E7D32,color:#000;
  classDef backend fill:#FFE5B4,stroke:#BF360C,color:#000;
  classDef db fill:#E0E0E0,stroke:#424242,color:#000;
  classDef external fill:#F8D7DA,stroke:#B71C1C,color:#000;
```
