# gocrane/crane architecture

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

- Interactive diagram: https://gitdiagram.com/gocrane/crane
- Repository: https://github.com/gocrane/crane

## Overview

##### Main Components
- Craned: The central component managing CRDs and APIs. This is the operator that runs as a Deployment (with two containers – one for CRD management, predictors, and one for WebApi/dashboard support).
- Dashboard: The web UI built using TDesign’s Starter, which interacts with Craned to provide cost insights and optimization recommendations.
- Fadvisor: A module (or service) responsible for collecting cloud resource pricing and billing data from multiple cloud providers.
- Metric Adapter: Implements the custom/external metric API for autoscaling and HPA. It uses Crane CRDs to expose metrics.
- Crane Agent: A DaemonSet that runs on each node, collecting node-level metrics and data for local visibility.
- Additional Components: Other modules such as recommendation framework, autoscaling estimators, load-aware scheduling, and QoS enhancers are visible in the pkg directory. They underpin prediction-driven autoscaling, recommendation rules for workload optimization, and interference detection.

##### Relationships and Interactions
- Craned interfaces with all internal subsystems (prediction modules, recommendation controllers, CRD management) and exposes APIs for the Dashboard.
- The Dashboard interacts with Craned to fetch analytical insights and to present real-time data (and might also talk to supplemental services like the Metric Adapter).
- Fadvisor collects external data (from cloud pricing APIs) and feeds data into the system (possibly updating CRDs or presenting metrics).
- The Metric Adapter consumes the Crane-specific CRDs and then supplies custom and external metrics to the Kubernetes HPA.
- Crane Agent residing on every node gathers local metrics, ensuring that real resource usage is fed back into the system.
- Several controller and executor components in the pkg directory (e.g., for autoscaling, ensurance, prediction, recommendation) work together by communicating via Kubernetes APIs or internally through function calls.

##### Architectural Patterns and Design Principles
- Microservices and modular design: The project is organized into multiple cmd packages (for each individual service or agent) and a comprehensive pkg directory that encapsulates the business logic and controllers.
- Kubernetes-native design: Use of CRDs, Deployments, DaemonSets, and custom controllers indicate that the system is designed as a cloud-native application.
- Separation of concerns: The system clearly demarcates responsibilities between analytics (Fadvisor), control (Craned), user interface (Dashboard), and metric handling (Metric Adapter).
- Pluggable extension: The recommendation framework and prediction modules are designed in a way that allows for additional recommenders or data providers to be added easily.

##### Incorporating Technologies, Frameworks, and Libraries
- Languages/Frameworks: Written in Go, with common Go tooling (Makefile, Dockerfile, golangci.yaml). The front-end uses TDesign and is built with modern web frameworks (TypeScript, Vite, React components).
- Kubernetes: Core to architecture – CRDs, Deployments, DaemonSets, and various Kubernetes YAML manifests in the deploy/ directory.
- Monitoring: Integration with Prometheus (via the Metric Adapter and custom metrics) and other data-exporting components.
- Additional components, such as exporters, prediction engines (DSP and percentile algorithms), are part of the technical stack.

##### Essential Architectural Elements
- How extensible modules (for example, various recommenders and prediction strategies) plug into the main control plane.
- Detail the relationship with external systems: Prometheus for monitoring, cloud providers for pricing data, and even integration with external dashboards.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Services
    subgraph "Backend Services"
        Craned["Craned (Operators & Predictors)"]:::backend
        Fadvisor["Fadvisor (Pricing Exporter)"]:::backend
        MetricAdapter["Metric Adapter (Custom Metrics API)"]:::backend
        Autoscaling["Autoscaling & Prediction Modules"]:::backend
        Recommendation["Recommendation Framework"]:::backend
        QoSEnsurance["QoS Enhancers & Ensurance Modules"]:::backend
    end

    %% Agents & Nodes
    subgraph "Agents & Nodes"
        CraneAgent["Crane Agent (Node-Level Collector)"]:::agent
    end

    %% Frontend/UI
    subgraph "Frontend"
        Dashboard["Dashboard (Web UI)"]:::frontend
    end

    %% Relationships
    Dashboard -->|"APIcalls"| Craned
    CraneAgent -->|"SendsMetrics"| Craned
    Fadvisor -->|"CloudPricingData"| Craned
    Fadvisor -->|"FeedsData"| Recommendation
    Craned -->|"UtilizesMetrics"| MetricAdapter
    Craned -->|"TriggersAutoscaling"| Autoscaling
    Craned -->|"InitiatesRecs"| Recommendation
    Craned -->|"AppliesQoS"| QoSEnsurance

    %% Styles
    classDef backend fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef frontend fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef agent fill:#ffcc99,stroke:#000,stroke-width:1px;

    %% Click Events
    click Craned "https://github.com/gocrane/crane/blob/main/cmd/craned/main.go"
    click Fadvisor "https://github.com/gocrane/crane/blob/main/pkg/recommend/advisor/advisor.go"
    click MetricAdapter "https://github.com/gocrane/crane/blob/main/cmd/metric-adapter/main.go"
    click CraneAgent "https://github.com/gocrane/crane/blob/main/cmd/crane-agent/main.go"
    click Dashboard "https://github.com/gocrane/crane/blob/main/pkg/web/index.html"
    click Autoscaling "https://github.com/gocrane/crane/blob/main/pkg/autoscaling/estimator/estimator.go"
    click Recommendation "https://github.com/gocrane/crane/blob/main/pkg/recommendation/config/config.go"
    click QoSEnsurance "https://github.com/gocrane/crane/tree/main/pkg/ensurance/analyzer"
```
