# nutyworks/codon architecture

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

## Overview

Codon is a Minecraft command debugger. A player issues controls or inspects debugger views in the client; client networking carries requests to server handlers, which use the debugger engine to pause, step, and report execution state. Minecraft hooks capture command execution, while adapters provide pause control and world data; client state and UI present the resulting inspection tools. The tree indicates breakpoint, watch/NBT, source-browsing, execution-flow, and freecam capabilities. README is empty, and sampled implementation is partial, so uncertain subsystem wiring is omitted.

Main entry points: [`src/core/java/works/nuty/codon/core/service/DebuggerEngine.java`](https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/service/DebuggerEngine.java) (Debugger engine), [`src/main/java/works/nuty/codon/network/DebuggerRequestHandler.java`](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/DebuggerRequestHandler.java) (Debugger requests), [`src/main/java/works/nuty/codon/network/NetworkDebuggerEventSink.java`](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/NetworkDebuggerEventSink.java) (Network event sink), [`src/client/java/works/nuty/codon/client/input/InputManager.java`](https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/input/InputManager.java) (Debugger controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client debugger"]
  node_clientmod["Client entry"]
  node_input["Debugger controls<br/>[InputManager.java]"]
  node_ui["Debugger screens"]
  node_clientstate["Client inspection state"]
  node_flowtimeline["Flow timeline"]
  node_freecam["Freecam"]
end

subgraph group_transport["Networking"]
  node_clientnetwork["Client networking"]
  node_sourcenetwork["Source browse client"]
  node_network["Payload registration"]
  node_requesthandler["Debugger requests"]
  node_sourcebrowse["Source browsing"]
end

subgraph group_server["Server debugging"]
  node_command["Debugger commands<br/>[CodonCommand.java]"]
  node_engine["Debugger engine"]
  node_breakpoints["Breakpoint registry"]
  node_stepping["Step controller"]
  node_flow["Flow recording"]
  node_sink["Network event sink"]
end

subgraph group_runtime["Minecraft runtime"]
  node_hooks["Command hooks"]
  node_controller["Pause controller"]
  node_watchreader["Watch evaluation<br/>[WatchReader.java]"]
  node_nbtreader["NBT tree reader<br/>[NbtTreeReader.java]"]
  node_source["Function sources"]
end

subgraph group_data["Persistence and models"]
  node_persistence[("World persistence")]
  node_watchpersistence[("Watch persistence")]
  node_models["Debugger models<br/>[PauseSnapshot.java]"]
end

node_player(("Player"))

node_player -->|"uses controls"| node_input
node_player -->|"inspects state"| node_ui
node_clientmod -->|"registers"| node_input
node_input -->|"checks pause"| node_clientstate
node_input -->|"sends requests"| node_clientnetwork
node_ui -->|"renders state"| node_clientstate
node_clientstate -->|"tracks history"| node_flowtimeline
node_clientmod -->|"integrates"| node_freecam
node_clientnetwork -->|"exchanges payloads"| node_network
node_sourcenetwork -->|"exchanges requests"| node_sourcebrowse
node_network -->|"dispatches"| node_requesthandler
node_requesthandler -->|"controls execution"| node_engine
node_command -->|"controls execution"| node_engine
node_hooks -->|"reports stages"| node_engine
node_engine -->|"checks and updates"| node_breakpoints
node_engine -->|"checks step mode"| node_stepping
node_engine -->|"records execution"| node_flow
node_engine -->|"parks execution"| node_controller
node_engine -->|"publishes events"| node_sink
node_sink -->|"sends updates"| node_network
node_requesthandler -->|"queries watches"| node_watchreader
node_requesthandler -->|"queries NBT"| node_nbtreader
node_sourcebrowse -->|"reads sources"| node_source
node_breakpoints -.->|"saved by"| node_persistence
node_watchreader -.->|"uses definitions"| node_watchpersistence
node_engine -->|"builds snapshots"| node_models
node_sink -->|"syncs debugger state"| node_clientstate
node_sink -->|"syncs flow history"| node_flowtimeline

click node_clientmod "https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/CodonClientMod.java"
click node_input "https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/input/InputManager.java"
click node_ui "https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/ui/DebuggerOverlay.java"
click node_clientstate "https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/state/ClientDebuggerState.java"
click node_flowtimeline "https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/state/ExecutionFlowTimeline.java"
click node_freecam "https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/camera/DebuggerFreecam.java"
click node_clientnetwork "https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/network/ClientNetworking.java"
click node_sourcenetwork "https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/network/ClientSourceBrowseNetworking.java"
click node_network "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/CodonNetworking.java"
click node_requesthandler "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/DebuggerRequestHandler.java"
click node_sourcebrowse "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/SourceBrowseNetworking.java"
click node_command "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/command/CodonCommand.java"
click node_engine "https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/service/DebuggerEngine.java"
click node_breakpoints "https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/service/BreakpointRegistry.java"
click node_stepping "https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/service/StepController.java"
click node_flow "https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/service/ExecutionFlowRecorder.java"
click node_sink "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/NetworkDebuggerEventSink.java"
click node_hooks "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/mixin/CommandFunctionMixin.java"
click node_controller "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/adapter/McExecutionController.java"
click node_watchreader "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/adapter/WatchReader.java"
click node_nbtreader "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/adapter/NbtTreeReader.java"
click node_source "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/adapter/FunctionSourceRepository.java"
click node_persistence "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/persistence/WorldBreakpointPersistence.java"
click node_watchpersistence "https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/persistence/WorldWatchPersistence.java"
click node_models "https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/model/PauseSnapshot.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_clientmod,node_input,node_ui,node_clientstate,node_flowtimeline,node_freecam toneBlue
class node_clientnetwork,node_sourcenetwork,node_network,node_requesthandler,node_sourcebrowse toneAmber
class node_command,node_engine,node_breakpoints,node_stepping,node_flow,node_sink toneMint
class node_hooks,node_controller,node_watchreader,node_nbtreader,node_source toneRose
class node_persistence,node_watchpersistence,node_models,node_player toneIndigo
```

## Components

### Client debugger

- [Client entry](https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/CodonClientMod.java): `src/client/java/works/nuty/codon/client/CodonClientMod.java`
- [Debugger controls](https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/input/InputManager.java): `src/client/java/works/nuty/codon/client/input/InputManager.java`
- [Debugger screens](https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/ui/DebuggerOverlay.java): `src/client/java/works/nuty/codon/client/ui/DebuggerOverlay.java`
- [Client inspection state](https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/state/ClientDebuggerState.java): `src/client/java/works/nuty/codon/client/state/ClientDebuggerState.java`
- [Flow timeline](https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/state/ExecutionFlowTimeline.java): `src/client/java/works/nuty/codon/client/state/ExecutionFlowTimeline.java`
- [Freecam](https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/camera/DebuggerFreecam.java): `src/client/java/works/nuty/codon/client/camera/DebuggerFreecam.java`

### Networking

- [Client networking](https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/network/ClientNetworking.java): `src/client/java/works/nuty/codon/client/network/ClientNetworking.java`
- [Source browse client](https://github.com/nutyworks/codon/blob/main/src/client/java/works/nuty/codon/client/network/ClientSourceBrowseNetworking.java): `src/client/java/works/nuty/codon/client/network/ClientSourceBrowseNetworking.java`
- [Payload registration](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/CodonNetworking.java): `src/main/java/works/nuty/codon/network/CodonNetworking.java`
- [Debugger requests](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/DebuggerRequestHandler.java): `src/main/java/works/nuty/codon/network/DebuggerRequestHandler.java`
- [Source browsing](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/SourceBrowseNetworking.java): `src/main/java/works/nuty/codon/network/SourceBrowseNetworking.java`

### Server debugging

- [Debugger commands](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/command/CodonCommand.java): `src/main/java/works/nuty/codon/command/CodonCommand.java`
- [Debugger engine](https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/service/DebuggerEngine.java): `src/core/java/works/nuty/codon/core/service/DebuggerEngine.java`
- [Breakpoint registry](https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/service/BreakpointRegistry.java): `src/core/java/works/nuty/codon/core/service/BreakpointRegistry.java`
- [Step controller](https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/service/StepController.java): `src/core/java/works/nuty/codon/core/service/StepController.java`
- [Flow recording](https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/service/ExecutionFlowRecorder.java): `src/core/java/works/nuty/codon/core/service/ExecutionFlowRecorder.java`
- [Network event sink](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/network/NetworkDebuggerEventSink.java): `src/main/java/works/nuty/codon/network/NetworkDebuggerEventSink.java`

### Minecraft runtime

- [Command hooks](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/mixin/CommandFunctionMixin.java): `src/main/java/works/nuty/codon/mixin/CommandFunctionMixin.java`
- [Pause controller](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/adapter/McExecutionController.java): `src/main/java/works/nuty/codon/adapter/McExecutionController.java`
- [Watch evaluation](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/adapter/WatchReader.java): `src/main/java/works/nuty/codon/adapter/WatchReader.java`
- [NBT tree reader](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/adapter/NbtTreeReader.java): `src/main/java/works/nuty/codon/adapter/NbtTreeReader.java`
- [Function sources](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/adapter/FunctionSourceRepository.java): `src/main/java/works/nuty/codon/adapter/FunctionSourceRepository.java`

### Persistence and models

- [World persistence](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/persistence/WorldBreakpointPersistence.java): `src/main/java/works/nuty/codon/persistence/WorldBreakpointPersistence.java`
- [Watch persistence](https://github.com/nutyworks/codon/blob/main/src/main/java/works/nuty/codon/persistence/WorldWatchPersistence.java): `src/main/java/works/nuty/codon/persistence/WorldWatchPersistence.java`
- [Debugger models](https://github.com/nutyworks/codon/blob/main/src/core/java/works/nuty/codon/core/model/PauseSnapshot.java): `src/core/java/works/nuty/codon/core/model/PauseSnapshot.java`

### Other components

- **Player**

## Connections

- Player → Debugger controls: uses controls
- Player → Debugger screens: inspects state
- Client entry → Debugger controls: registers
- Debugger controls → Client inspection state: checks pause
- Debugger controls → Client networking: sends requests
- Debugger screens → Client inspection state: renders state
- Client inspection state → Flow timeline: tracks history
- Client entry → Freecam: integrates
- Client networking → Payload registration: exchanges payloads
- Source browse client → Source browsing: exchanges requests
- Payload registration → Debugger requests: dispatches
- Debugger requests → Debugger engine: controls execution
- Debugger commands → Debugger engine: controls execution
- Command hooks → Debugger engine: reports stages
- Debugger engine → Breakpoint registry: checks and updates
- Debugger engine → Step controller: checks step mode
- Debugger engine → Flow recording: records execution
- Debugger engine → Pause controller: parks execution
- Debugger engine → Network event sink: publishes events
- Network event sink → Payload registration: sends updates
- Debugger requests → Watch evaluation: queries watches
- Debugger requests → NBT tree reader: queries NBT
- Source browsing → Function sources: reads sources
- Breakpoint registry → World persistence: saved by
- Watch evaluation → Watch persistence: uses definitions
- Debugger engine → Debugger models: builds snapshots
- Network event sink → Client inspection state: syncs debugger state
- Network event sink → Flow timeline: syncs flow history