# rayonlabs/chutes architecture

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

- Interactive diagram: https://gitdiagram.com/rayonlabs/chutes
- Repository: https://github.com/rayonlabs/chutes

## Overview

##### Project Type and Purpose
- This is a Python-based SDK and CLI tool (“chutes”) for building, deploying, and running containerized AI applications (“chutes”) on the chutes.ai platform.
- It provides:
- A local CLI client for user workflows (register, build, deploy, run)
- A library for programmatically constructing Docker images (`chutes.image`)
- A library for defining FastAPI-style applications (“chutes”) via decorators (`chutes.chute`)
- Integration points for authentication (Bittensor hotkeys) and GPU validation (GraVal)

##### Main Components
1) Developer / Client Layer
- “chutes” CLI (chutes/cli.py + entrypoint/* subcommands)
- SDK modules (config, constants, util, crud)
- Local Docker context (–local builds, examples/)
2) Control-Plane / Platform Layer
- Chutes API server (external microservice, not in this repo)
- Remote build service (receives Docker context, builds images)
- Container registry (stores built images)
- Orchestrator / scheduler (schedules containers on GPU hosts)
3) Data-Plane / Compute Layer
- GPU Miner Nodes
- GraVal middleware inside each running chute for GPU authenticity
- FastAPI application processes (cord endpoints)

##### Relationships and Data Flows
- Developer invokes `chutes <command>` → local CLI parses command via entrypoint modules →
– HTTP call to Chutes API for auth, registration, key management
– HTTP call to remote build service (if `build --wait` or remote build) with Docker directives from `chutes.image.Image`
– HTTP call to deploy endpoint with metadata from `chutes.chute` (template, NodeSelector, concurrency)
- Remote build service → builds Docker image → pushes to container registry → notifies API server
- Deploy API → orchestrator schedules container on a miner → miner pulls image → starts FastAPI server
- Client applications or end users → HTTP calls to deployed chute’s public_api_path endpoints → requests handled by FastAPI methods decorated via `@chute.cord` → compute on GPU
- At container startup, GraVal middleware decrypts/validates traffic with validator service

##### Architectural Patterns & Design Principles
- Microservices: separate API server, build service, orchestrator
- Command Pattern: CLI entrypoints modularized under `chutes/entrypoint`
- Plugin/Template System: `chutes.chute.template.*` and `chutes.image.directive.*`
- Decorator-driven routing: FastAPI-like `@chute.cord` for automatic OpenAPI schema generation
- Containerization: Docker image DSL built in Python, remote vs local execution contexts
- Security: Bittensor hotkey auth, GraVal GPU validation

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Developer / Client Layer"
    CLI["Chutes CLI"]:::dev
    Entry["CLI Subcommands"]:::dev
    Config["Config Module"]:::dev
    Constants["Constants Module"]:::dev
    CRUD["CRUD Module"]:::dev
    Util["Utility Functions"]:::dev
    ImageDSL["Local Docker Image Builder DSL"]:::dev
    ChuteLib["Chute Definition Library"]:::dev
    Examples["Local Docker Context"]:::dev
  end

  subgraph "Control-Plane / Platform Layer"
    API["Chutes API Server"]:::ctrl
    BuildService["Remote Build Service"]:::ctrl
    Registry["Container Registry"]:::ctrl
    Orchestrator["Orchestrator / Scheduler"]:::ctrl
  end

  subgraph "Data-Plane / Compute Layer"
    Miner["GPU Miner Node"]:::data
    GraVal["GraVal GPU Validation Middleware"]:::data
    FastAPIApp["FastAPI Chute Process"]:::data
  end

  Client["Client Application / End User"]:::external

  CLI -->|"HTTP REST (Auth,Register,Keys)"| API
  CLI -->|"HTTP REST Build"| BuildService
  CLI -->|"HTTP REST Deploy"| API
  BuildService -->|"push image"| Registry
  API -->|"schedule"| Orchestrator
  Orchestrator -->|"start container"| Miner
  Miner -->|"pull image"| Registry
  Miner -->|"run container"| FastAPIApp
  FastAPIApp -->|"uses middleware"| GraVal
  Client -->|"HTTP REST Calls"| FastAPIApp

  click CLI "https://github.com/rayonlabs/chutes/blob/main/chutes/cli.py"
  click Entry "https://github.com/rayonlabs/chutes/tree/main/chutes/entrypoint/"
  click Config "https://github.com/rayonlabs/chutes/blob/main/chutes/config.py"
  click Constants "https://github.com/rayonlabs/chutes/blob/main/chutes/constants.py"
  click CRUD "https://github.com/rayonlabs/chutes/blob/main/chutes/crud.py"
  click Util "https://github.com/rayonlabs/chutes/tree/main/chutes/util/"
  click ImageDSL "https://github.com/rayonlabs/chutes/tree/main/chutes/image/"
  click ChuteLib "https://github.com/rayonlabs/chutes/tree/main/chutes/chute/"
  click Examples "https://github.com/rayonlabs/chutes/tree/main/examples/"

  classDef dev fill:#cce5ff,stroke:#004085,color:#004085
  classDef ctrl fill:#d4edda,stroke:#155724,color:#155724
  classDef data fill:#ffe5cc,stroke:#e8590c,color:#e8590c
  classDef external fill:#f8f9fa,stroke:#6c757d,color:#6c757d
```
