# phasetranscrystal/topology architecture

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

- Interactive diagram: https://gitdiagram.com/phasetranscrystal/topology
- Repository: https://github.com/phasetranscrystal/topology

## Overview

Topology is a NeoForge library mod that gives downstream mods declarative infrastructure rather than adding gameplay itself. The main workflow is a mod implementing and registering a TopoPlugin; TopoPluginEngine then bootstraps the registered domains, which provide machine, recipe, material, equipment, pipe, and ore capabilities in-game. The graph preserves those distinct domains and highlights multiblock recognition and pipe-network surveying as internal runtime layers. README documents additional capabilities whose exact runtime wiring is not shown in the sampled source; those links are left out where uncertain.

Main entry points: [`src/main/java/net/ptcrys/topo/api/api/plugin/TopoPluginEngine.java`](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/api/plugin/TopoPluginEngine.java) (Domain bootstrap), [`src/main/java/net/ptcrys/topo/api/pipe/network/PipeNetworkEngine.java`](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/pipe/network/PipeNetworkEngine.java) (Pipe network runtime), [`src/main/java/net/ptcrys/topo/api/pipe/survey/PipeSurveyManager.java`](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/pipe/survey/PipeSurveyManager.java) (Network survey), [`src/main/java/net/ptcrys/topo/api/api/plugin/TopoPlugins.java`](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/api/plugin/TopoPlugins.java) (Plugin registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Plugin bootstrap"]
  node_plugins["Plugin registration<br/>[TopoPlugins.java]"]
  node_bootstrap["Domain bootstrap"]
end

subgraph group_machine["Machine runtime"]
  node_machines["Machine definitions<br/>[Machines.java]"]
  node_components["Machine components"]
  node_resources["Resource ports<br/>[ResourcePort.java]"]
  node_machine_data["Machine data sync"]
  node_multiblock["Multiblock controller"]
  node_structure["Structure recognition"]
end

subgraph group_recipe["Recipes"]
  node_recipe_types["Recipe types"]
  node_recipe_search["Recipe search"]
  node_production["Production lines"]
end

subgraph group_materials["Materials and equipment"]
  node_material["Material registry"]
  node_forms["Material forms"]
  node_processors["Material processing"]
  node_equipment["Equipment registry"]
end

subgraph group_pipes["Pipe networks"]
  node_pipe_engine["Pipe network runtime"]
  node_pipe_runtime["Per-level networks"]
  node_survey["Network survey"]
  node_survey_client["Survey renderer"]
end

subgraph group_ore["Ore generation"]
  node_ore_veins["Ore vein registry<br/>[OreVeins.java]"]
  node_ore_worldgen["Ore worldgen planner"]
end

node_downstream(("Downstream mod"))

node_downstream -->|"registers plugin"| node_plugins
node_plugins -->|"supplies plugins"| node_bootstrap
node_bootstrap -->|"bootstraps recipes"| node_recipe_types
node_bootstrap -->|"bootstraps materials"| node_material
node_bootstrap -->|"bootstraps machines"| node_machines
node_bootstrap -->|"bootstraps equipment"| node_equipment
node_bootstrap -->|"freezes pipe setup"| node_pipe_engine
node_bootstrap -->|"bootstraps ore"| node_ore_veins
node_multiblock -->|"recognizes structure"| node_structure
node_recipe_search -->|"searches types"| node_recipe_types
node_material -->|"registers forms"| node_forms
node_bootstrap -->|"runs processors"| node_processors
node_pipe_engine -->|"dispatches level events"| node_pipe_runtime
node_pipe_engine -->|"forwards pipe hooks"| node_pipe_runtime
node_survey -->|"gets network runtime"| node_pipe_engine
node_survey -->|"sends snapshot"| node_survey_client
node_ore_worldgen -->|"reads frozen veins"| node_ore_veins

click node_plugins "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/api/plugin/TopoPlugins.java"
click node_bootstrap "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/api/plugin/TopoPluginEngine.java"
click node_machines "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/Machines.java"
click node_components "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/component/MachineComponents.java"
click node_resources "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/resource/ResourcePort.java"
click node_machine_data "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/data/MachineDataSyncBatcher.java"
click node_multiblock "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/multiblock/MultiblockController.java"
click node_structure "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/multiblock/pattern/StructureEngine.java"
click node_recipe_types "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/recipe/TopoRecipeTypes.java"
click node_recipe_search "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/recipe/search/TopoRecipeSearchIndex.java"
click node_production "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/recipe/productionline/ProductionLines.java"
click node_material "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/material/MaterialRegistry.java"
click node_forms "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/material/form/MaterialFormRegistry.java"
click node_processors "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/material/process/MaterialPostProcessorRegistry.java"
click node_equipment "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/equipment/EquipmentRegistry.java"
click node_pipe_engine "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/pipe/network/PipeNetworkEngine.java"
click node_pipe_runtime "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/pipe/network/PipeLevelRuntime.java"
click node_survey "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/pipe/survey/PipeSurveyManager.java"
click node_survey_client "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/client/survey/PipeSurveyClientRenderer.java"
click node_ore_veins "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/ore/OreVeins.java"
click node_ore_worldgen "https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/ore/engine/OreWorldgenService.java"

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_plugins,node_bootstrap toneBlue
class node_machines,node_components,node_resources,node_machine_data,node_multiblock,node_structure toneAmber
class node_recipe_types,node_recipe_search,node_production toneMint
class node_material,node_forms,node_processors,node_equipment toneRose
class node_pipe_engine,node_pipe_runtime,node_survey,node_survey_client,node_downstream toneIndigo
class node_ore_veins,node_ore_worldgen toneTeal
```

## Components

### Plugin bootstrap

- [Plugin registration](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/api/plugin/TopoPlugins.java): `src/main/java/net/ptcrys/topo/api/api/plugin/TopoPlugins.java`
- [Domain bootstrap](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/api/plugin/TopoPluginEngine.java): `src/main/java/net/ptcrys/topo/api/api/plugin/TopoPluginEngine.java`

### Machine runtime

- [Machine definitions](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/Machines.java): `src/main/java/net/ptcrys/topo/api/machine/Machines.java`
- [Machine components](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/component/MachineComponents.java): `src/main/java/net/ptcrys/topo/api/machine/component/MachineComponents.java`
- [Resource ports](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/resource/ResourcePort.java): `src/main/java/net/ptcrys/topo/api/machine/resource/ResourcePort.java`
- [Machine data sync](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/data/MachineDataSyncBatcher.java): `src/main/java/net/ptcrys/topo/api/machine/data/MachineDataSyncBatcher.java`
- [Multiblock controller](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/multiblock/MultiblockController.java): `src/main/java/net/ptcrys/topo/api/machine/multiblock/MultiblockController.java`
- [Structure recognition](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/machine/multiblock/pattern/StructureEngine.java): `src/main/java/net/ptcrys/topo/api/machine/multiblock/pattern/StructureEngine.java`

### Recipes

- [Recipe types](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/recipe/TopoRecipeTypes.java): `src/main/java/net/ptcrys/topo/api/recipe/TopoRecipeTypes.java`
- [Recipe search](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/recipe/search/TopoRecipeSearchIndex.java): `src/main/java/net/ptcrys/topo/api/recipe/search/TopoRecipeSearchIndex.java`
- [Production lines](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/recipe/productionline/ProductionLines.java): `src/main/java/net/ptcrys/topo/api/recipe/productionline/ProductionLines.java`

### Materials and equipment

- [Material registry](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/material/MaterialRegistry.java): `src/main/java/net/ptcrys/topo/api/material/MaterialRegistry.java`
- [Material forms](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/material/form/MaterialFormRegistry.java): `src/main/java/net/ptcrys/topo/api/material/form/MaterialFormRegistry.java`
- [Material processing](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/material/process/MaterialPostProcessorRegistry.java): `src/main/java/net/ptcrys/topo/api/material/process/MaterialPostProcessorRegistry.java`
- [Equipment registry](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/equipment/EquipmentRegistry.java): `src/main/java/net/ptcrys/topo/api/equipment/EquipmentRegistry.java`

### Pipe networks

- [Pipe network runtime](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/pipe/network/PipeNetworkEngine.java): `src/main/java/net/ptcrys/topo/api/pipe/network/PipeNetworkEngine.java`
- [Per-level networks](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/pipe/network/PipeLevelRuntime.java): `src/main/java/net/ptcrys/topo/api/pipe/network/PipeLevelRuntime.java`
- [Network survey](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/pipe/survey/PipeSurveyManager.java): `src/main/java/net/ptcrys/topo/api/pipe/survey/PipeSurveyManager.java`
- [Survey renderer](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/client/survey/PipeSurveyClientRenderer.java): `src/main/java/net/ptcrys/topo/client/survey/PipeSurveyClientRenderer.java`

### Ore generation

- [Ore vein registry](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/ore/OreVeins.java): `src/main/java/net/ptcrys/topo/api/ore/OreVeins.java`
- [Ore worldgen planner](https://github.com/phasetranscrystal/topology/blob/master/src/main/java/net/ptcrys/topo/api/ore/engine/OreWorldgenService.java): `src/main/java/net/ptcrys/topo/api/ore/engine/OreWorldgenService.java`

### Other components

- **Downstream mod**

## Connections

- Downstream mod → Plugin registration: registers plugin
- Plugin registration → Domain bootstrap: supplies plugins
- Domain bootstrap → Recipe types: bootstraps recipes
- Domain bootstrap → Material registry: bootstraps materials
- Domain bootstrap → Machine definitions: bootstraps machines
- Domain bootstrap → Equipment registry: bootstraps equipment
- Domain bootstrap → Pipe network runtime: freezes pipe setup
- Domain bootstrap → Ore vein registry: bootstraps ore
- Multiblock controller → Structure recognition: recognizes structure
- Recipe search → Recipe types: searches types
- Material registry → Material forms: registers forms
- Domain bootstrap → Material processing: runs processors
- Pipe network runtime → Per-level networks: dispatches level events
- Pipe network runtime → Per-level networks: forwards pipe hooks
- Network survey → Pipe network runtime: gets network runtime
- Network survey → Survey renderer: sends snapshot
- Ore worldgen planner → Ore vein registry: reads frozen veins
