# sereneee1201/magic architecture

> Architecture diagram of the GitHub repository sereneee1201/magic, 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/sereneee1201/magic
- Repository: https://github.com/sereneee1201/magic

## Overview

MAGIC turns a natural-language request for connected scenes into generated 3D environments, then composes them into Unity output. The main workflow separates multi-scene planning, per-scene conceptual design, object and geometry production, and rendering/export; evaluation and prompt-dataset generation are separate product capabilities. The graph follows documented orchestration and sampled calls; several detailed generation modules are represented by their existing enclosing directories because their implementation was not sampled.

Main entry points: [`magic/generation/main.py`](https://github.com/sereneee1201/magic/blob/main/magic/generation/main.py) (Scene generator), [`magic/utils/llm.py`](https://github.com/sereneee1201/magic/blob/main/magic/utils/llm.py) (LLM client), [`magic/pipeline.py`](https://github.com/sereneee1201/magic/blob/main/magic/pipeline.py) (Multi-scene pipeline), [`magic/generation/modules/object_placement`](https://github.com/sereneee1201/magic/tree/main/magic/generation/modules/object_placement) (Object placement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Scene orchestration"]
  node_pipeline["Multi-scene pipeline<br/>[pipeline.py]"]
  node_planner["Scene planner<br/>[planner.py]"]
  node_generator["Scene generator<br/>[main.py]"]
end

subgraph group_design["Scene design"]
  node_llm["LLM client<br/>[llm.py]"]
  node_prompt["Prompt processing"]
  node_concept["Scene conceptualization"]
  node_constraints["DSL constraints"]
  node_composition["Scene composition<br/>[composition.py]"]
  node_object_placement["Object placement"]
end

subgraph group_assets["3D assets"]
  node_retriever["Asset retrieval<br/>[retriever.py]"]
  node_asset_store[("ObjaTHOR assets")]
  node_shape_gen["Shape generation<br/>[generator.py]"]
  node_mesh["Mesh utilities<br/>[mesh.py]"]
  node_rotation["Object rotation<br/>[rotation.py]"]
end

subgraph group_output["Rendering and export"]
  node_blender["Blender renderer<br/>[brender.py]"]
  node_unity["Unity scene export<br/>[main.py]"]
  node_combine["Scene combination<br/>[combine.py]"]
  node_unity_runtime["Unity runtime"]
end

subgraph group_evaluation["Evaluation and data"]
  node_eval_pipeline["Evaluation pipeline<br/>[eval_pipeline.py]"]
  node_eval_files["Evaluation file tools<br/>[eval_files.py]"]
  node_eval_portal["Portal analysis<br/>[eval_portal.py]"]
  node_dataset["Prompt dataset generator<br/>[main.py]"]
end

node_user(("Prompt author"))
node_result["Generated Unity scenes"]

node_user -->|"provides prompt"| node_pipeline
node_pipeline -->|"plans scenes"| node_planner
node_planner -->|"queries"| node_llm
node_pipeline -->|"generates scenes"| node_generator
node_generator -->|"processes prompt"| node_prompt
node_generator -->|"designs scene"| node_concept
node_generator -->|"checks constraints"| node_constraints
node_generator -->|"places objects"| node_object_placement
node_generator -->|"composes scene"| node_composition
node_prompt -->|"queries"| node_llm
node_concept -->|"queries"| node_llm
node_object_placement -->|"retrieves assets"| node_retriever
node_retriever -->|"loads assets"| node_asset_store
node_object_placement -.->|"generates shapes"| node_shape_gen
node_generator -->|"renders objects"| node_blender
node_rotation -->|"renders views"| node_blender
node_rotation -->|"requests rotation"| node_llm
node_pipeline -->|"exports scenes"| node_unity
node_unity -->|"creates project"| node_unity_runtime
node_pipeline -->|"combines outputs"| node_combine
node_combine -->|"writes result"| node_result
node_unity -->|"writes scenes"| node_result
node_user -->|"requests evaluation"| node_eval_pipeline
node_eval_pipeline -->|"reads case files"| node_eval_files
node_eval_pipeline -->|"analyzes portals"| node_eval_portal
node_eval_portal -->|"queries"| node_llm
node_user -->|"requests prompts"| node_dataset
node_dataset -->|"generates descriptions"| node_llm

click node_pipeline "https://github.com/sereneee1201/magic/blob/main/magic/pipeline.py"
click node_planner "https://github.com/sereneee1201/magic/blob/main/magic/planner.py"
click node_generator "https://github.com/sereneee1201/magic/blob/main/magic/generation/main.py"
click node_llm "https://github.com/sereneee1201/magic/blob/main/magic/utils/llm.py"
click node_prompt "https://github.com/sereneee1201/magic/tree/main/magic/generation/modules/prompt_processing"
click node_concept "https://github.com/sereneee1201/magic/tree/main/magic/generation/modules/scene_conceptualization"
click node_constraints "https://github.com/sereneee1201/magic/tree/main/magic/generation/dsl"
click node_composition "https://github.com/sereneee1201/magic/blob/main/magic/generation/composition.py"
click node_object_placement "https://github.com/sereneee1201/magic/tree/main/magic/generation/modules/object_placement"
click node_retriever "https://github.com/sereneee1201/magic/blob/main/magic/object/objrtv/objathor/retriever.py"
click node_shape_gen "https://github.com/sereneee1201/magic/blob/main/magic/object/objgen/shap_e/generator.py"
click node_mesh "https://github.com/sereneee1201/magic/blob/main/magic/utils/mesh.py"
click node_rotation "https://github.com/sereneee1201/magic/blob/main/magic/object/rotation.py"
click node_blender "https://github.com/sereneee1201/magic/blob/main/magic/blender/brender.py"
click node_unity "https://github.com/sereneee1201/magic/blob/main/magic/unity/main.py"
click node_combine "https://github.com/sereneee1201/magic/blob/main/magic/combine.py"
click node_eval_pipeline "https://github.com/sereneee1201/magic/blob/main/eval_agent/eval_pipeline.py"
click node_eval_files "https://github.com/sereneee1201/magic/blob/main/eval_agent/eval_files.py"
click node_eval_portal "https://github.com/sereneee1201/magic/blob/main/eval_agent/eval_portal.py"
click node_dataset "https://github.com/sereneee1201/magic/blob/main/magic/dataset/main.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_pipeline,node_planner,node_generator toneBlue
class node_llm,node_prompt,node_concept,node_constraints,node_composition,node_object_placement toneAmber
class node_retriever,node_asset_store,node_shape_gen,node_mesh,node_rotation toneMint
class node_blender,node_unity,node_combine,node_unity_runtime toneRose
class node_eval_pipeline,node_eval_files,node_eval_portal,node_dataset,node_user,node_result toneIndigo
```

## Components

### Scene orchestration

- [Multi-scene pipeline](https://github.com/sereneee1201/magic/blob/main/magic/pipeline.py): `magic/pipeline.py`
- [Scene planner](https://github.com/sereneee1201/magic/blob/main/magic/planner.py): `magic/planner.py`
- [Scene generator](https://github.com/sereneee1201/magic/blob/main/magic/generation/main.py): `magic/generation/main.py`

### Scene design

- [LLM client](https://github.com/sereneee1201/magic/blob/main/magic/utils/llm.py): `magic/utils/llm.py`
- [Prompt processing](https://github.com/sereneee1201/magic/tree/main/magic/generation/modules/prompt_processing): `magic/generation/modules/prompt_processing`
- [Scene conceptualization](https://github.com/sereneee1201/magic/tree/main/magic/generation/modules/scene_conceptualization): `magic/generation/modules/scene_conceptualization`
- [DSL constraints](https://github.com/sereneee1201/magic/tree/main/magic/generation/dsl): `magic/generation/dsl`
- [Scene composition](https://github.com/sereneee1201/magic/blob/main/magic/generation/composition.py): `magic/generation/composition.py`
- [Object placement](https://github.com/sereneee1201/magic/tree/main/magic/generation/modules/object_placement): `magic/generation/modules/object_placement`

### 3D assets

- [Asset retrieval](https://github.com/sereneee1201/magic/blob/main/magic/object/objrtv/objathor/retriever.py): `magic/object/objrtv/objathor/retriever.py`
- **ObjaTHOR assets**
- [Shape generation](https://github.com/sereneee1201/magic/blob/main/magic/object/objgen/shap_e/generator.py): `magic/object/objgen/shap_e/generator.py`
- [Mesh utilities](https://github.com/sereneee1201/magic/blob/main/magic/utils/mesh.py): `magic/utils/mesh.py`
- [Object rotation](https://github.com/sereneee1201/magic/blob/main/magic/object/rotation.py): `magic/object/rotation.py`

### Rendering and export

- [Blender renderer](https://github.com/sereneee1201/magic/blob/main/magic/blender/brender.py): `magic/blender/brender.py`
- [Unity scene export](https://github.com/sereneee1201/magic/blob/main/magic/unity/main.py): `magic/unity/main.py`
- [Scene combination](https://github.com/sereneee1201/magic/blob/main/magic/combine.py): `magic/combine.py`
- **Unity runtime**

### Evaluation and data

- [Evaluation pipeline](https://github.com/sereneee1201/magic/blob/main/eval_agent/eval_pipeline.py): `eval_agent/eval_pipeline.py`
- [Evaluation file tools](https://github.com/sereneee1201/magic/blob/main/eval_agent/eval_files.py): `eval_agent/eval_files.py`
- [Portal analysis](https://github.com/sereneee1201/magic/blob/main/eval_agent/eval_portal.py): `eval_agent/eval_portal.py`
- [Prompt dataset generator](https://github.com/sereneee1201/magic/blob/main/magic/dataset/main.py): `magic/dataset/main.py`

### Other components

- **Prompt author**
- **Generated Unity scenes**

## Connections

- Prompt author → Multi-scene pipeline: provides prompt
- Multi-scene pipeline → Scene planner: plans scenes
- Scene planner → LLM client: queries
- Multi-scene pipeline → Scene generator: generates scenes
- Scene generator → Prompt processing: processes prompt
- Scene generator → Scene conceptualization: designs scene
- Scene generator → DSL constraints: checks constraints
- Scene generator → Object placement: places objects
- Scene generator → Scene composition: composes scene
- Prompt processing → LLM client: queries
- Scene conceptualization → LLM client: queries
- Object placement → Asset retrieval: retrieves assets
- Asset retrieval → ObjaTHOR assets: loads assets
- Object placement → Shape generation: generates shapes
- Scene generator → Blender renderer: renders objects
- Object rotation → Blender renderer: renders views
- Object rotation → LLM client: requests rotation
- Multi-scene pipeline → Unity scene export: exports scenes
- Unity scene export → Unity runtime: creates project
- Multi-scene pipeline → Scene combination: combines outputs
- Scene combination → Generated Unity scenes: writes result
- Unity scene export → Generated Unity scenes: writes scenes
- Prompt author → Evaluation pipeline: requests evaluation
- Evaluation pipeline → Evaluation file tools: reads case files
- Evaluation pipeline → Portal analysis: analyzes portals
- Portal analysis → LLM client: queries
- Prompt author → Prompt dataset generator: requests prompts
- Prompt dataset generator → LLM client: generates descriptions