# juicedata/juicefs-csi-driver architecture

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

- Interactive diagram: https://gitdiagram.com/juicedata/juicefs-csi-driver
- Repository: https://github.com/juicedata/juicefs-csi-driver

## Overview

##### Project type and purpose
- This is a Kubernetes CSI (Container Storage Interface) Driver for JuiceFS, written in Go.
- It provides volume provisioning, attach/detach, mount/unmount on Kubernetes nodes, plus an optional Dashboard (backend+React frontend) and webhook components.
- Key indicators:
- “cmd/” contains controller, node, dashboard binaries.
- “pkg/driver”, “pkg/controller”, “pkg/fuse”, “pkg/juicefs” implement the CSI patterns.
- “deploy/” holds Kubernetes manifests.
- “dashboard-ui-v2” is a React/TypeScript frontend.

##### File structure
- Top-level “cmd/”:
- cmd/main.go – CSI controller manager entry point
- cmd/node.go  – CSI node plugin entry point
- cmd/dashboard – Dashboard API server
- cmd/app / cmd/pod_manager  – controller implementations
- “pkg/driver”, “pkg/controller”, “pkg/webhook”: core CSI logic, controller-runtime reconciler, admission webhooks.
- “pkg/fuse”, “pkg/juicefs”: mount logic (spawn FUSE, process mounts).
- “dashboard-ui-v2”: a separate React SPA.
- “deploy/” & “docker/”: manifest and image builds.
- CI workflows and test directories for e2e, chaos and validation in “tests/”.

##### README for additional insights
- Confirms purpose: “JuiceFS CSI Driver allows you to use JuiceFS in Kubernetes.”

##### Details
- CSI sub-components (identity, controller, node, provisioner logic in “pkg/driver”).
- Deployment method (Kustomize overlays under “deploy/”).
- Don’t over-complicate: break into Frontend, Backend, CSI Controller, CSI Node, Webhook, External Storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster" 
        direction TB
        K8sApi["Kubernetes API Server"]:::kube

        subgraph "CSI Components"
            direction TB
            CSIController["CSI Controller\n(cmd/main)"]:::kube
            CSIDriverCore["CSI Driver Core Logic\n(pkg/driver)"]:::kube
            ControllerRuntime["Controller-Runtime\n(pkg/controller)"]:::kube
            CSINode["CSI Node Plugin\n(cmd/node)"]:::kube
            FUSELogic["FUSE Mount Logic\n(pkg/fuse)"]:::kube
            JuiceFSLogic["JuiceFS Mount & Process Logic\n(pkg/juicefs)"]:::kube
        end

        subgraph "Admission Webhook"
            direction TB
            AdmissionWebhook["Admission Webhook\n(pkg/webhook/handler)"]:::kube
        end

        subgraph "Dashboard"
            direction TB
            DashboardBackend["Dashboard Backend API\n(cmd/dashboard/main.go)"]:::ui
            DashboardBackendPkg["Dashboard Backend Logic\n(pkg/dashboard)"]:::ui
            DashboardFrontend["Dashboard Frontend\n(React SPA)"]:::ui
        end

        Manifests["K8s Manifests\n(deploy/kubernetes)"]:::kube
        DockerCSI["CSI Dockerfile\n(docker/csi.Dockerfile)"]:::kube
        DockerDash["Dashboard Dockerfile\n(docker/dashboard.Dockerfile)"]:::kube
        Tests["E2E & Validation Tests\n(tests)"]:::kube
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ExternalMeta["JuiceFS MetaServer"]:::external
        ExternalStorage["Object Storage\n(S3/OSS)"]:::external
    end

    %% Connections
    CSIController -->|"gRPC CSI"| K8sApi
    CSINode -->|"gRPC CSI"| K8sApi
    CSIController -->|"uses"| CSIDriverCore
    CSIController -->|"reconcile"| ControllerRuntime
    CSINode -->|"mount logic"| FUSELogic
    FUSELogic -->|"spawn FUSE"| JuiceFSLogic
    JuiceFSLogic -->|"I/O"| ExternalMeta
    JuiceFSLogic -->|"I/O"| ExternalStorage
    AdmissionWebhook -->|"intercepts"| K8sApi
    DashboardBackend -->|"k8s client"| K8sApi
    DashboardBackend -->|"implements API"| DashboardBackendPkg
    DashboardFrontend -->|"REST API"| DashboardBackend
    Manifests --> CSIController
    Manifests --> CSINode
    Manifests --> AdmissionWebhook
    Manifests --> DashboardBackend
    Manifests --> DashboardFrontend
    DockerCSI --> CSIController
    DockerCSI --> CSINode
    DockerDash --> DashboardFrontend
    Tests -.-> CSIController
    Tests -.-> CSINode
    Tests -.-> DashboardBackend
    Tests -.-> ExternalServices

    %% Click Events
    click CSIController "https://github.com/juicedata/juicefs-csi-driver/blob/master/cmd/main.go"
    click CSINode "https://github.com/juicedata/juicefs-csi-driver/blob/master/cmd/node.go"
    click CSIDriverCore "https://github.com/juicedata/juicefs-csi-driver/tree/master/pkg/driver"
    click ControllerRuntime "https://github.com/juicedata/juicefs-csi-driver/tree/master/pkg/controller"
    click FUSELogic "https://github.com/juicedata/juicefs-csi-driver/tree/master/pkg/fuse"
    click JuiceFSLogic "https://github.com/juicedata/juicefs-csi-driver/tree/master/pkg/juicefs"
    click AdmissionWebhook "https://github.com/juicedata/juicefs-csi-driver/tree/master/pkg/webhook/handler"
    click DashboardBackend "https://github.com/juicedata/juicefs-csi-driver/blob/master/cmd/dashboard/main.go"
    click DashboardBackendPkg "https://github.com/juicedata/juicefs-csi-driver/tree/master/pkg/dashboard"
    click DashboardFrontend "https://github.com/juicedata/juicefs-csi-driver/tree/master/dashboard-ui-v2"
    click Manifests "https://github.com/juicedata/juicefs-csi-driver/tree/master/deploy/kubernetes"
    click DockerCSI "https://github.com/juicedata/juicefs-csi-driver/blob/master/docker/csi.Dockerfile"
    click DockerDash "https://github.com/juicedata/juicefs-csi-driver/blob/master/docker/dashboard.Dockerfile"
    click Tests "https://github.com/juicedata/juicefs-csi-driver/tree/master/tests"

    %% Styles
    classDef kube fill:#d0e7ff,stroke:#4a90e2,color:#004085;
    classDef external fill:#e2f0d9,stroke:#3c763d,color:#155724;
    classDef ui fill:#fff3cd,stroke:#856404,color:#856404;
    classDef storage fill:#e2f0d9,stroke:#3c763d,color:#155724;
```
