# yuyz0112/dewhale architecture

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

- Interactive diagram: https://gitdiagram.com/yuyz0112/dewhale
- Repository: https://github.com/yuyz0112/dewhale

## Overview

##### Project Type and Purpose
- Dewhale is an AI-powered tool that leverages GitHub integration to generate code and facilitate effortless development. In essence, it serves as a GitHub-powered “MCP host”.
- The README emphasizes its role in prompt engineering with GPT-4 and seamless GitHub integration – meaning the system is a hybrid between a backend service for processing AI-based commands and a frontend that exposes functionalities (as seen in the “website” directory).

##### File Structure Analysis
- Top-Level Directories:
- The “dewhale” directory holds configuration elements and character definitions (YAML files) that likely inform or customize the AI’s behavior.
- The “src” directory contains the core logic written in TypeScript. Look here for the main entry point (entry.ts) and library modules (lib/) such as config.ts, llm.ts (likely interfacing with GPT-based language models), mcp.ts (centralized MCP logic), and platform.ts (integration layer, possibly encapsulating GitHub functions).
- The “.github” folder contains GitHub Actions workflows (e.g., dewhale-trigger.yaml and release.yml) which show the automation aspects and CI/CD integration.
- The “website” folder is the frontend portion (notice Astro configurations, components, pages) and represents the UI/dashboard that might be used by end-users.
- Configuration and integration cues:
- The “dewhale/config.yaml” and character YAML files inside “dewhale/characters” are instrumental in customizing the AI or UI behavior.
- The presence of build configuration, TS config, and package.json in the website folder indicates structured front-end development.

a. Main Components:
- Frontend: Represented by the “website” directory. This component is built with frameworks (Astro) and provides UI functionality.
- Backend/Core Engine: The “src” directory houses the core modules – the entry point, configuration module, LLM integration, MCP logic, and platform integration.
- Configuration & Customization Layer: The “dewhale” directory, particularly the config.yaml and character YAML files, serves as the source of customization inputs.
- GitHub Integration & CI/CD: The .github/workflows directory represents automated trigger systems and deployment pipelines. This coupling gives the system its “GitHub-powered” nature.
- Documentation: The “docs” folder which provides architecture and use-case guidelines and may be referenced in development for maintaining consistency.

b. Relationships and Interactions:
- The Frontend interacts with the Backend by sending requests (for instance, triggering the generation process or displaying results generated via AI).
- The Backend (src modules) uses configuration data (from dewhale config files) to control prompt engineering and AI interactions (llm.ts) with the GPT-4 model.
- The MCP module (mcp.ts) manages GitHub integration, storing generated code to GitHub repos and handling version control.
- GitHub Actions (from the .github folder) automatically trigger tasks such as code generation or release workflows, linking the repository state with the backend processing.
- External integrations are visible via the use of third-party libraries like shadcn/ui, lucide, and nivo charts as mentioned in the README.

c. Architectural Patterns / Design Principles:
- Modularization: The clear separation between configuration (dewhale/), core logic (src/), and UI (website/) is a key design element.
- Separation of Concerns & Layering: Frontend layers (website) are distinct from the backend engine layers (src) and the configuration settings.
- Integration-Driven: GitHub Actions and CI/CD workflows emphasize the project’s reliance on external automation and version control.
- Customizability: The open-sourced prompt (as stated in the README) and configuration allow easy customization, implying that the system is designed with flexibility in mind.

d. Relevant Technologies, Frameworks, and Libraries:
- TypeScript for core backend logic.
- Astro (a modern framework) for the frontend.
- GitHub Actions for CI/CD.
- GPT-4 based LLM integration (as indicated by llm.ts) and prompt engineering.
- External UI libraries (shadcn/ui, lucide, nivo charts) that are referenced in the README for generating UI components.

##### Elements
- Frontend/UI (website) with noted technologies such as Astro.
- Backend processing engine (src), including entry point and modules (config, llm, mcp, platform).
- Configuration module (dewhale/ config.yaml and character YAMLs).
- CI/CD and automation (GitHub Actions workflows).
- External integration points (GitHub API, LLM service endpoints).
- Data flow from the frontend to the backend.
- Configuration data into the processing engine.
- Trigger, processing, and deployment flow through GitHub Actions.
- Feedback loops where results and outputs are displayed back on the UI.

##### Final Recommendations
- Be thorough—include every major component and show the interdependencies.
- Avoid oversimplifying; separate as many logical layers as the file structure and README justify.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration Layer"
        config["Configuration (config.yaml)"]:::config
        characters["Character YAMLs (Issac, Miles, Taylor)"]:::config
    end

    subgraph "Backend Processing Engine"
        entry["Entry Point (src/entry.ts)"]:::backend
        confModule["Config Module (src/lib/config.ts)"]:::backend
        llmModule["LLM Integration (src/lib/llm.ts)"]:::backend
        mcpModule["MCP Module (src/lib/mcp.ts)"]:::backend
        platformModule["Platform Integration (src/lib/platform.ts)"]:::backend
    end

    subgraph "Frontend/UI Layer"
        frontend["Frontend UI (Astro)"]:::frontend
    end

    subgraph "GitHub Integration & CI/CD"
        githubActions["GitHub Actions Workflows"]:::ci
    end

    subgraph "Documentation"
        docs["Documentation"]:::docs
    end

    %% Relationships
    frontend -->|"triggers"| entry
    config -->|"provides"| confModule
    characters -->|"provides"| confModule
    confModule -->|"configures"| entry
    entry -->|"processes"| llmModule
    entry -->|"processes"| mcpModule
    entry -->|"leverages"| platformModule
    mcpModule -->|"deploys"| githubActions
    mcpModule -->|"returns"| frontend
    docs -->|"informs"| frontend

    %% Click Events
    click frontend "https://github.com/yuyz0112/dewhale/tree/v2/website/"
    click entry "https://github.com/yuyz0112/dewhale/blob/v2/src/entry.ts"
    click confModule "https://github.com/yuyz0112/dewhale/blob/v2/src/lib/config.ts"
    click llmModule "https://github.com/yuyz0112/dewhale/blob/v2/src/lib/llm.ts"
    click mcpModule "https://github.com/yuyz0112/dewhale/blob/v2/src/lib/mcp.ts"
    click platformModule "https://github.com/yuyz0112/dewhale/blob/v2/src/lib/platform.ts"
    click config "https://github.com/yuyz0112/dewhale/blob/v2/dewhale/config.yaml"
    click characters "https://github.com/yuyz0112/dewhale/tree/v2/dewhale/characters"
    click githubActions "https://github.com/yuyz0112/dewhale/tree/v2/.github/workflows/"
    click docs "https://github.com/yuyz0112/dewhale/tree/v2/docs/"

    %% Styles
    classDef frontend fill:#FFCC00,stroke:#000,stroke-width:2px;
    classDef backend fill:#66CCFF,stroke:#000,stroke-width:2px;
    classDef config fill:#CCFFCC,stroke:#000,stroke-width:2px;
    classDef ci fill:#FF9999,stroke:#000,stroke-width:2px;
    classDef docs fill:#CCCCFF,stroke:#000,stroke-width:2px;
```
