# zed-0xff/zombiebuddy architecture
> Architecture diagram of the GitHub repository zed-0xff/zombiebuddy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/zed-0xff/zombiebuddy
- Repository: https://github.com/zed-0xff/zombiebuddy
## Overview
ZombieBuddy is a Java agent framework for Project Zomboid modding. The main workflow is to start the agent with the game, discover and load Java mods, interpret their declarative patches, and transform game classes at runtime; it also exposes Java functionality to Lua. The README documents mod signing, installation, runtime retransformation, and logging as additional capabilities. Internal edges below rely on README-level descriptions where excerpts do not show the full call chain; experimental HTTP/Lua tooling is shown separately, with its wiring evidenced by the sampled sources.
Main entry points: [`java/src/main/java/me/zed_0xff/zombie_buddy/Loader.java`](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Loader.java) (Mod loader), [`java/src/main/java/me/zed_0xff/zombie_buddy/PatchEngine.java`](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/PatchEngine.java) (Patch engine), [`java/src/main/java/me/zed_0xff/zombie_buddy/ModApprovalsStore.java`](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/ModApprovalsStore.java) (Mod approval), [`java/src/main/java/me/zed_0xff/zombie_buddy/Agent.java`](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Agent.java) (Java agent)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_startup["Startup and mods"]
node_agent["Java agent
[Agent.java]"]
node_loader["Mod loader
[Loader.java]"]
node_approval[("Mod approval")]
node_approval_ui["Approval frontends"]
node_signing["Author trust
[KnownAuthors.java]"]
end
subgraph group_patching["Runtime patching"]
node_patch_api["Patch annotations
[Patch.java]"]
node_patch_engine["Patch engine
[PatchEngine.java]"]
node_transformer["Patch transformer"]
node_pipeline["Transform pipeline
[Pipeline.java]"]
node_jar_context["Class context
[JarContext.java]"]
end
subgraph group_lua["Lua integration"]
node_lua_exposer["Lua exposure
[Exposer.java]"]
node_lua_api["Lua API
[ZombieBuddy.java]"]
node_http_server["Experimental HTTP
[HttpServer.java]"]
node_lua_handler["Lua request handler
[LuaHandler.java]"]
end
subgraph group_tools["Support capabilities"]
node_logger["Logging
[Logger.java]"]
node_jar_dump["JAR inspection
[Main.java]"]
node_installer["Windows installer
[installer.go]"]
end
node_modder(("Modder"))
node_game["Project Zomboid"]
node_modder -->|"declares patches"| node_patch_api
node_agent -->|"loads mods"| node_loader
node_loader -.->|"checks trust"| node_approval
node_approval -.->|"prompts user"| node_approval_ui
node_signing -.->|"informs trust"| node_approval
node_loader -->|"discovers patches"| node_patch_engine
node_patch_engine -->|"interprets annotations"| node_patch_api
node_patch_engine -->|"installs patches"| node_transformer
node_transformer -->|"transforms classes"| node_game
node_pipeline -->|"uses class context"| node_jar_context
node_modder -->|"exposes Java"| node_lua_exposer
node_lua_exposer -.->|"provides Lua API"| node_lua_api
node_http_server -->|"routes requests"| node_lua_handler
node_lua_handler -->|"executes Lua"| node_game
node_agent -->|"configures verbosity"| node_logger
node_modder -->|"inspects bytecode"| node_jar_dump
node_modder -->|"installs on Windows"| node_installer
click node_agent "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Agent.java"
click node_loader "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Loader.java"
click node_approval "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/ModApprovalsStore.java"
click node_approval_ui "https://github.com/zed-0xff/zombiebuddy/tree/master/java/src/main/java/me/zed_0xff/zombie_buddy/frontend"
click node_signing "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/KnownAuthors.java"
click node_patch_api "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/annotations/Patch.java"
click node_patch_engine "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/PatchEngine.java"
click node_transformer "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/PatchTransformer.java"
click node_pipeline "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/transformers/Pipeline.java"
click node_jar_context "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/transformers/JarContext.java"
click node_lua_exposer "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Exposer.java"
click node_lua_api "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/ZombieBuddy.java"
click node_http_server "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/patches/experimental/HttpServer.java"
click node_lua_handler "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/patches/experimental/http/LuaHandler.java"
click node_logger "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Logger.java"
click node_jar_dump "https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/jardump/Main.java"
click node_installer "https://github.com/zed-0xff/zombiebuddy/blob/master/installer/installer.go"
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_agent,node_loader,node_approval,node_approval_ui,node_signing toneBlue
class node_patch_api,node_patch_engine,node_transformer,node_pipeline,node_jar_context toneAmber
class node_lua_exposer,node_lua_api,node_http_server,node_lua_handler toneMint
class node_logger,node_jar_dump,node_installer toneRose
class node_modder,node_game toneIndigo
```
## Components
### Startup and mods
- [Java agent](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Agent.java): `java/src/main/java/me/zed_0xff/zombie_buddy/Agent.java`
- [Mod loader](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Loader.java): `java/src/main/java/me/zed_0xff/zombie_buddy/Loader.java`
- [Mod approval](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/ModApprovalsStore.java): `java/src/main/java/me/zed_0xff/zombie_buddy/ModApprovalsStore.java`
- [Approval frontends](https://github.com/zed-0xff/zombiebuddy/tree/master/java/src/main/java/me/zed_0xff/zombie_buddy/frontend): `java/src/main/java/me/zed_0xff/zombie_buddy/frontend`
- [Author trust](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/KnownAuthors.java): `java/src/main/java/me/zed_0xff/zombie_buddy/KnownAuthors.java`
### Runtime patching
- [Patch annotations](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/annotations/Patch.java): `java/src/main/java/me/zed_0xff/zombie_buddy/annotations/Patch.java`
- [Patch engine](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/PatchEngine.java): `java/src/main/java/me/zed_0xff/zombie_buddy/PatchEngine.java`
- [Patch transformer](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/PatchTransformer.java): `java/src/main/java/me/zed_0xff/zombie_buddy/PatchTransformer.java`
- [Transform pipeline](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/transformers/Pipeline.java): `java/src/main/java/me/zed_0xff/zombie_buddy/transformers/Pipeline.java`
- [Class context](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/transformers/JarContext.java): `java/src/main/java/me/zed_0xff/zombie_buddy/transformers/JarContext.java`
### Lua integration
- [Lua exposure](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Exposer.java): `java/src/main/java/me/zed_0xff/zombie_buddy/Exposer.java`
- [Lua API](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/ZombieBuddy.java): `java/src/main/java/me/zed_0xff/zombie_buddy/ZombieBuddy.java`
- [Experimental HTTP](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/patches/experimental/HttpServer.java): `java/src/main/java/me/zed_0xff/zombie_buddy/patches/experimental/HttpServer.java`
- [Lua request handler](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/patches/experimental/http/LuaHandler.java): `java/src/main/java/me/zed_0xff/zombie_buddy/patches/experimental/http/LuaHandler.java`
### Support capabilities
- [Logging](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/Logger.java): `java/src/main/java/me/zed_0xff/zombie_buddy/Logger.java`
- [JAR inspection](https://github.com/zed-0xff/zombiebuddy/blob/master/java/src/main/java/me/zed_0xff/zombie_buddy/jardump/Main.java): `java/src/main/java/me/zed_0xff/zombie_buddy/jardump/Main.java`
- [Windows installer](https://github.com/zed-0xff/zombiebuddy/blob/master/installer/installer.go): `installer/installer.go`
### Other components
- **Modder**
- **Project Zomboid**
## Connections
- Modder → Patch annotations: declares patches (evidence: `README.md`)
- Java agent → Mod loader: loads mods (evidence: `README.md`)
- Mod loader → Mod approval: checks trust
- Mod approval → Approval frontends: prompts user
- Author trust → Mod approval: informs trust
- Mod loader → Patch engine: discovers patches (evidence: `README.md`)
- Patch engine → Patch annotations: interprets annotations (evidence: `java/src/main/java/me/zed_0xff/zombie_buddy/PatchEngine.java`)
- Patch engine → Patch transformer: installs patches (evidence: `java/src/main/java/me/zed_0xff/zombie_buddy/PatchEngine.java`)
- Patch transformer → Project Zomboid: transforms classes (evidence: `README.md`)
- Transform pipeline → Class context: uses class context (evidence: `java/src/main/java/me/zed_0xff/zombie_buddy/transformers/Pipeline.java`)
- Modder → Lua exposure: exposes Java (evidence: `README.md`)
- Lua exposure → Lua API: provides Lua API (evidence: `java/src/main/java/me/zed_0xff/zombie_buddy/ZombieBuddy.java`)
- Experimental HTTP → Lua request handler: routes requests (evidence: `java/src/main/java/me/zed_0xff/zombie_buddy/patches/experimental/HttpServer.java`)
- Lua request handler → Project Zomboid: executes Lua (evidence: `java/src/main/java/me/zed_0xff/zombie_buddy/patches/experimental/http/LuaHandler.java`)
- Java agent → Logging: configures verbosity (evidence: `java/src/main/java/me/zed_0xff/zombie_buddy/Agent.java`)
- Modder → JAR inspection: inspects bytecode (evidence: `java/src/main/java/me/zed_0xff/zombie_buddy/jardump/Main.java`)
- Modder → Windows installer: installs on Windows (evidence: `README.md`)