# cssu/terrain-diffusion architecture

> Architecture diagram of the GitHub repository cssu/terrain-diffusion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cssu/terrain-diffusion
- Repository: https://github.com/cssu/terrain-diffusion
- Video tour (about a minute): https://gitdiagram.com/cssu/terrain-diffusion/video

## Overview

terrain-diffusion is a planned reproduction of InfiniteDiffusion for deterministic, seamless, effectively infinite terrain generation. The main workflow accepts a seed and region, generates overlapping noisy patches, blends them into height grids, and exposes results as files or through an HTTP service for a browser-based 3D view. The README describes the intended architecture, but much of the Python code is still planning documentation and the web app is a placeholder; edges below follow those documented responsibilities where implementation is not present. Model inference, elevation encoding, benchmarking, and optional tile persistence are also represented.

Main entry points: [`src/terrain_diffusion/orchestration.py`](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/orchestration.py) (Generation Orchestration), [`src/terrain_diffusion/sampler.py`](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/sampler.py) (Windowed Blending Sampler), [`src/terrain_diffusion/pipeline.py`](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/pipeline.py) (Model Pipeline), [`src/terrain_diffusion/inference.py`](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/inference.py) (Model Inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Terrain Generation"]
  node_orchestration["Generation Orchestration<br/>[orchestration.py]"]
  node_sampler["Windowed Blending Sampler<br/>[sampler.py]"]
end

subgraph group_models["Model Processing"]
  node_pipeline["Model Pipeline<br/>[pipeline.py]"]
  node_inference["Model Inference<br/>[inference.py]"]
  node_encoding["Elevation Encoding<br/>[encoding.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_cli["Output and CLI<br/>[cli.py]"]
  node_visualizer["3D Visualizer"]
  node_service["Generation Service<br/>[service.py]"]
end

subgraph group_evaluation["Evaluation and State"]
  node_store[("Terrain Store<br/>[store.py]")]
  node_benchmark["Benchmarking and Evaluation<br/>[benchmark.py]"]
end

node_user(("User"))
node_weights["Pretrained Weights"]
node_gpu["GPU Compute"]
node_disk[("Local Disk Cache")]
node_files["Output Files"]

node_user -->|"requests terrain"| node_cli
node_user -->|"explores terrain"| node_visualizer
node_cli -->|"requests region"| node_orchestration
node_orchestration -->|"generates region"| node_sampler
node_sampler -->|"cleans patches"| node_pipeline
node_pipeline -->|"runs models"| node_inference
node_pipeline -->|"decodes elevations"| node_encoding
node_sampler -->|"writes and reads tiles"| node_store
node_orchestration -->|"reads height grids"| node_store
node_cli -->|"writes results"| node_files
node_visualizer -->|"requests over HTTP"| node_service
node_service -->|"requests region"| node_orchestration
node_benchmark -->|"evaluates generation"| node_orchestration
node_inference -.->|"loads weights"| node_weights
node_inference -.->|"runs inference"| node_gpu
node_store -.->|"persists tiles"| node_disk

click node_cli "https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/cli.py"
click node_visualizer "https://github.com/cssu/terrain-diffusion/tree/main/web"
click node_service "https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/service.py"
click node_orchestration "https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/orchestration.py"
click node_sampler "https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/sampler.py"
click node_store "https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/store.py"
click node_pipeline "https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/pipeline.py"
click node_inference "https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/inference.py"
click node_encoding "https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/encoding.py"
click node_benchmark "https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/benchmark.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_orchestration,node_sampler,node_user toneBlue
class node_pipeline,node_inference,node_encoding,node_disk toneAmber
class node_cli,node_visualizer,node_service toneMint
class node_store,node_benchmark toneRose
class node_weights,node_gpu,node_files toneIndigo
```

## Components

### Terrain Generation

- [Generation Orchestration](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/orchestration.py): `src/terrain_diffusion/orchestration.py`
- [Windowed Blending Sampler](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/sampler.py): `src/terrain_diffusion/sampler.py`

### Model Processing

- [Model Pipeline](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/pipeline.py): `src/terrain_diffusion/pipeline.py`
- [Model Inference](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/inference.py): `src/terrain_diffusion/inference.py`
- [Elevation Encoding](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/encoding.py): `src/terrain_diffusion/encoding.py`

### User Interfaces

- [Output and CLI](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/cli.py): `src/terrain_diffusion/cli.py`
- [3D Visualizer](https://github.com/cssu/terrain-diffusion/tree/main/web): `web`
- [Generation Service](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/service.py): `src/terrain_diffusion/service.py`

### Evaluation and State

- [Terrain Store](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/store.py): `src/terrain_diffusion/store.py`
- [Benchmarking and Evaluation](https://github.com/cssu/terrain-diffusion/blob/main/src/terrain_diffusion/benchmark.py): `src/terrain_diffusion/benchmark.py`

### Other components

- **User**
- **Pretrained Weights**
- **GPU Compute**
- **Local Disk Cache**
- **Output Files**

## Connections

- User → Output and CLI: requests terrain
- User → 3D Visualizer: explores terrain
- Output and CLI → Generation Orchestration: requests region
- Generation Orchestration → Windowed Blending Sampler: generates region
- Windowed Blending Sampler → Model Pipeline: cleans patches
- Model Pipeline → Model Inference: runs models
- Model Pipeline → Elevation Encoding: decodes elevations
- Windowed Blending Sampler → Terrain Store: writes and reads tiles
- Generation Orchestration → Terrain Store: reads height grids
- Output and CLI → Output Files: writes results
- 3D Visualizer → Generation Service: requests over HTTP
- Generation Service → Generation Orchestration: requests region
- Benchmarking and Evaluation → Generation Orchestration: evaluates generation
- Model Inference → Pretrained Weights: loads weights
- Model Inference → GPU Compute: runs inference
- Terrain Store → Local Disk Cache: persists tiles