# keplar-404/ace-step1.5-for-cloud-deployment architecture

> Architecture diagram of the GitHub repository keplar-404/ace-step1.5-for-cloud-deployment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keplar-404/ace-step1.5-for-cloud-deployment
- Repository: https://github.com/keplar-404/ace-step1.5-for-cloud-deployment

## Overview

ACE-Step 1.5 is an AI music-generation application with CLI and persistent API entry points. The central workflow accepts generation parameters, optionally uses the 5Hz language model for lyrics or metadata, runs DiT audio inference, and returns or saves generated audio. The README also documents covers, segment editing, multi-track generation, source separation, and track completion; these are represented as handler capabilities. Some internal wiring is inferred only where excerpts or documentation support it; unsampled subsystem links are omitted.

Main entry points: [`acestep/handler.py`](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py) (Generation handler), [`acestep/inference.py`](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/inference.py) (Generation API), [`acestep/llm_inference.py`](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/llm_inference.py) (Lyrics and metadata), [`acestep/model_downloader.py`](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/model_downloader.py) (Model downloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["Interactive CLI<br/>[cli.py]"]
  node_server["Inference API<br/>[server.py]"]
end

subgraph group_generation["Generation Workflow"]
  node_api["Generation API<br/>[inference.py]"]
  node_handler["Generation handler<br/>[handler.py]"]
  node_lyrics["Lyrics and metadata<br/>[llm_inference.py]"]
  node_audio["Audio output<br/>[inference.py]"]
  node_covers["Audio covers<br/>[handler.py]"]
  node_editing["Segment editing<br/>[handler.py]"]
  node_multitrack["Multi-track generation<br/>[handler.py]"]
  node_separation["Source separation<br/>[handler.py]"]
  node_completion["Track completion<br/>[handler.py]"]
end

subgraph group_models["Model Runtime"]
  node_dit["DiT models"]
  node_lm["5Hz LM<br/>[llm_inference.py]"]
  node_vllm["nano-vLLM backend<br/>[llm.py]"]
  node_downloader["Model downloader"]
end

subgraph group_extensions["Customization"]
  node_lora["LoRA management<br/>[lora_manager.py]"]
  node_lora_service["LoRA registry and scaling<br/>[service.py]"]
end

node_user(("Music creator"))

node_user -->|"requests music"| node_cli
node_user -->|"submits request"| node_server
node_cli -->|"starts generation"| node_api
node_server -->|"calls generation"| node_api
node_api -->|"generates lyrics and metadata"| node_lyrics
node_api -->|"requests audio inference"| node_handler
node_handler -->|"runs diffusion"| node_dit
node_api -->|"saves generated audio"| node_audio
node_api -.->|"uses optional LM"| node_lyrics
node_lyrics -->|"runs language model"| node_lm
node_lm -.->|"uses backend"| node_vllm
node_handler -->|"supports cover tasks"| node_covers
node_handler -->|"supports repaint tasks"| node_editing
node_handler -->|"supports instrument tasks"| node_multitrack
node_handler -->|"supports separation"| node_separation
node_handler -->|"supports track extension"| node_completion
node_downloader -->|"downloads model files"| node_dit
node_downloader -->|"downloads model files"| node_lm
node_handler -->|"manages adapters"| node_lora
node_lora -->|"uses registry and scaling"| node_lora_service

click node_cli "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/cli.py"
click node_server "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/server.py"
click node_api "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/inference.py"
click node_handler "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py"
click node_lyrics "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/llm_inference.py"
click node_audio "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/inference.py"
click node_covers "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py"
click node_editing "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py"
click node_multitrack "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py"
click node_separation "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py"
click node_completion "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py"
click node_dit "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/tree/main/acestep/models"
click node_lm "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/llm_inference.py"
click node_vllm "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/third_parts/nano-vllm/nanovllm/llm.py"
click node_downloader "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/model_downloader.py"
click node_lora "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/core/generation/handler/lora_manager.py"
click node_lora_service "https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/core/lora/service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_server toneBlue
class node_api,node_handler,node_lyrics,node_audio,node_covers,node_editing,node_multitrack,node_separation,node_completion toneAmber
class node_dit,node_lm,node_vllm,node_downloader toneMint
class node_lora,node_lora_service toneRose
class node_user toneIndigo
```

## Components

### User Interfaces

- [Interactive CLI](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/cli.py): `cli.py`
- [Inference API](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/server.py): `server.py`

### Generation Workflow

- [Generation API](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/inference.py): `acestep/inference.py`
- [Generation handler](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py): `acestep/handler.py`
- [Lyrics and metadata](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/llm_inference.py): `acestep/llm_inference.py`
- [Audio output](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/inference.py): `acestep/inference.py`
- [Audio covers](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py): `acestep/handler.py`
- [Segment editing](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py): `acestep/handler.py`
- [Multi-track generation](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py): `acestep/handler.py`
- [Source separation](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py): `acestep/handler.py`
- [Track completion](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/handler.py): `acestep/handler.py`

### Model Runtime

- [DiT models](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/tree/main/acestep/models): `acestep/models`
- [5Hz LM](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/llm_inference.py): `acestep/llm_inference.py`
- [nano-vLLM backend](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/third_parts/nano-vllm/nanovllm/llm.py): `acestep/third_parts/nano-vllm/nanovllm/llm.py`
- [Model downloader](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/model_downloader.py): `acestep/model_downloader.py`

### Customization

- [LoRA management](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/core/generation/handler/lora_manager.py): `acestep/core/generation/handler/lora_manager.py`
- [LoRA registry and scaling](https://github.com/keplar-404/ace-step1.5-for-cloud-deployment/blob/main/acestep/core/lora/service.py): `acestep/core/lora/service.py`

### Other components

- **Music creator**

## Connections

- Music creator → Interactive CLI: requests music
- Music creator → Inference API: submits request
- Interactive CLI → Generation API: starts generation
- Inference API → Generation API: calls generation
- Generation API → Lyrics and metadata: generates lyrics and metadata
- Generation API → Generation handler: requests audio inference
- Generation handler → DiT models: runs diffusion
- Generation API → Audio output: saves generated audio
- Generation API → Lyrics and metadata: uses optional LM
- Lyrics and metadata → 5Hz LM: runs language model
- 5Hz LM → nano-vLLM backend: uses backend
- Generation handler → Audio covers: supports cover tasks
- Generation handler → Segment editing: supports repaint tasks
- Generation handler → Multi-track generation: supports instrument tasks
- Generation handler → Source separation: supports separation
- Generation handler → Track completion: supports track extension
- Model downloader → DiT models: downloads model files
- Model downloader → 5Hz LM: downloads model files
- Generation handler → LoRA management: manages adapters
- LoRA management → LoRA registry and scaling: uses registry and scaling