# dragonflyoss/dragonfly architecture

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

- Interactive diagram: https://gitdiagram.com/dragonflyoss/dragonfly
- Repository: https://github.com/dragonflyoss/dragonfly

## Overview

Based on your project’s file tree and the README, Dragonfly is a large-scale, open source P2P file distribution and image acceleration system. Its purpose is to efficiently and securely distribute files in cloud native architectures by using a P2P approach, with distinct components managing everything from cluster configuration to task scheduling and file delivery.

##### Main Components
- Manager: This component manages the P2P cluster. It handles dynamic configuration, RBAC, authentication (including OAuth integrations found in the “manager/auth” directory), and offers a front-end console for operations. It exposes APIs for managing and monitoring cluster state.
- Scheduler: Responsible for selecting the optimal download parent (peer) during file distribution. It also manages scheduling policies, resource allocation, and integrates closely with job and quota management (see “scheduler/” directories, including job, resource, and RPC server components).
- Peer (Dfdaemon): This is the core of the P2P system deployed on client hosts. It provides file download capabilities and runs in two modes:
- Standard Peer Mode – as part of the P2P distribution mechanism.
- Seed Peer Mode – acting as a back-to-source component in scenarios where there are no eligible peers.
The “client/daemon” directory contains the implementation details (peer task management, object storage, proxy, and other networking protocols). Alongside dfdaemon, there is also the dfget command-line tool (located in “client/dfget”) that the end users leverage for initiating downloads.
- Additional Utilities: There is also dfcache and dfstore, which provide caching and file storage functionalities, respectively. These are important when considering how files are stored, retrieved, or managed across the network.

##### Interactions and Data Flow
- The client (via dfget) initiates a download request that is handled by a local dfdaemon (Peer).
- The Peer consults the Scheduler to determine the optimal source within the P2P cluster.
- If no eligible peer exists or in fallback scenarios, a Seed Peer is designated to fall back to the original source.
- Manager sits at a higher level, maintaining the overall state of clusters, managing configuration, and enforcing security or RBAC policies. It also exposes a RESTful API (and possibly gRPC, given the “pkg/rpc” directories) for the Scheduler and Peer to report status or retrieve configuration.
- These components talk to each other using clearly defined and versioned RPC mechanisms (for example, the “manager”, “scheduler”, and “dfdaemon” RPC endpoints under pkg/rpc), ensuring smooth communication among distributed nodes.

##### Architectural Patterns & Design Principles
- Modular Architecture: The project is clearly split into discrete modules (Manager, Scheduler, Peer) with their associated APIs and utilities. This modularity ensures separation of concerns.
- Microservices-like Interaction: Although all components share the same codebase, their directory structure and individual command folders (e.g., “cmd/manager”, “cmd/scheduler”, “cmd/dfget”) indicate service-like separation.
- P2P Principles: The core idea being P2P-based file distribution means the design should capture the dynamic relationships between peers, including fallback mechanisms via Seed Peer.
- Use of RPC and HTTP APIs: Communication among key components relies on robust RPC implementations and HTTP-based user interfaces/management consoles.

##### Technologies and Frameworks
- Programming Language: The entire project is implemented in Go.
- Containerization: The presence of Dockerfiles in “build/images”, “build/plugin-builder”, etc., hints at container deployment.
- Cloud Native Frameworks: As a CNCF project, it likely interacts with Kubernetes, containerd, and other cloud native technologies.
- Security & Authentication: OAuth integrations (see manager/auth/oauth) and middleware indicate that secure access and traffic encryption are core parts of the design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Control Plane"
        Manager["Manager"]:::manager
        Scheduler["Scheduler"]:::scheduler
    end

    subgraph "Data Plane"
        DFGet["End-User (dfget)"]:::client
        Peer["Peer (Dfdaemon)"]:::peer
        subgraph "Additional Utilities"
            DfCache["dfcache"]:::util
            DfStore["dfstore"]:::util
        end
    end

    %% Data Flow Connections
    DFGet -->|"DownloadRequest"| Peer
    Peer -->|"RPCcall"| Scheduler
    Scheduler -->|"SelectionResponse"| Peer
    Manager -->|"Config/StateUpdate"| Scheduler
    Manager -->|"Config/StateUpdate"| Peer
    Scheduler -->|"SeedPeerFallback"| Peer
    Peer -->|"CacheLookup"| DfCache
    Peer -->|"StoreRetrieval"| DfStore

    %% Click Events for Manager
    click Manager "https://github.com/dragonflyoss/dragonfly/tree/main/manager/"
    click Manager "https://github.com/dragonflyoss/dragonfly/blob/main/cmd/manager/main.go"
    click Manager "https://github.com/dragonflyoss/dragonfly/tree/main/api/manager/"
    click Manager "https://github.com/dragonflyoss/dragonfly/tree/main/manager/auth/oauth/"

    %% Click Events for Scheduler
    click Scheduler "https://github.com/dragonflyoss/dragonfly/tree/main/scheduler/"
    click Scheduler "https://github.com/dragonflyoss/dragonfly/blob/main/cmd/scheduler/main.go"
    click Scheduler "https://github.com/dragonflyoss/dragonfly/tree/main/scheduler/rpcserver/"
    click Scheduler "https://github.com/dragonflyoss/dragonfly/tree/main/scheduler/scheduling/"

    %% Click Events for Peer
    click Peer "https://github.com/dragonflyoss/dragonfly/tree/main/client/daemon/"
    click Peer "https://github.com/dragonflyoss/dragonfly/tree/main/client/daemon/peer/"
    click Peer "https://github.com/dragonflyoss/dragonfly/tree/main/client/daemon/rpcserver/"

    %% Click Events for End-User Download Tool (dfget)
    click DFGet "https://github.com/dragonflyoss/dragonfly/blob/main/client/dfget/dfget.go"
    click DFGet "https://github.com/dragonflyoss/dragonfly/blob/main/cmd/dfget/main.go"

    %% Click Events for Additional Utilities - dfcache
    click DfCache "https://github.com/dragonflyoss/dragonfly/blob/main/client/dfcache/dfcache.go"
    click DfCache "https://github.com/dragonflyoss/dragonfly/tree/main/cmd/dfcache/"

    %% Click Events for Additional Utilities - dfstore
    click DfStore "https://github.com/dragonflyoss/dragonfly/blob/main/client/dfstore/dfstore.go"
    click DfStore "https://github.com/dragonflyoss/dragonfly/tree/main/cmd/dfstore/"

    %% Styles
    classDef manager fill:#ADD8E6,stroke:#333,stroke-width:2px,color:#000;
    classDef scheduler fill:#90EE90,stroke:#333,stroke-width:2px,color:#000;
    classDef peer fill:#FFFF99,stroke:#333,stroke-width:2px,color:#000;
    classDef client fill:#FFC0CB,stroke:#333,stroke-width:2px,color:#000;
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:2px,color:#000;
```
