# nicholass003/axiom architecture

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

- Interactive diagram: https://gitdiagram.com/nicholass003/axiom
- Repository: https://github.com/nicholass003/axiom

## Overview

#### Purpose and Entry Point
Axiom is a PHP library for decoding/encoding and translating Minecraft Bedrock Edition packets across protocol versions. Consumers enter through `src/Axiom.php`, calling `Axiom::for($protocol)` to obtain a version-aware codec builder. It is a Composer-installed library, not a standalone server or application.

#### Protocol Selection and Inheritance
Protocol definitions select the available codecs and preserve compatibility through version layering. `src/Version/Protocol/ProtocolInterface.php` defines the protocol contract; concrete protocol maps live in files such as `src/Version/Protocol/Protocol844.php`, `src/Version/Protocol/Protocol898.php`, and `src/Version/Protocol/Protocol1001.php`. `src/Version/ProtocolVersion.php` represents supported protocol identifiers. New versions primarily add or override changed codecs rather than duplicating all packet handling.

#### Codec Dispatch Layer
`src/Codec/CodecBuilder.php` is the central lookup boundary between a packet ID and its version-specific codec. `src/Codec/Codec.php` defines the codec abstraction, while `src/Codec/CodecType.php` carries encode/decode context. The caller resolves a codec by packet ID, then invokes it with a binary reader/writer supplied by the host runtime.

#### Packet Model Boundary
Packet classes are version-neutral semantic models: each represents a Bedrock protocol message and its fields, independent of its wire layout. Core examples are `src/Packet/Packet.php`, `src/Packet/PacketIds.php`, and concrete packets such as `src/Packet/StartGamePacket.php`. This separates application-facing packet objects from protocol-specific binary serialization.

#### Version-Specific Wire Codecs
Per-version codecs implement each packet’s exact binary layout. The broad baseline is `src/Codec/v844/`; later versions contain only additions and layout overrides, e.g. `src/Codec/v898/StartGameCodec.php`, `src/Codec/v944/UpdateBlockCodec.php`, and `src/Codec/v1001/StartGameCodec.php`. Control flow is packet ID → builder lookup → selected version codec → packet object or encoded bytes.

#### Shared Serialization System
Reusable serializers handle compound protocol structures used by many packet codecs. `src/Codec/Common/Serializer/NetworkNbtSerializer.php`, `src/Codec/Common/Serializer/InventorySerializer.php`, and `src/Codec/Common/Serializer/LevelSettingsSerializer.php` encapsulate shared binary subformats. Version-specific serializer overrides, such as `src/Codec/v944/Serializer/LevelSettingsSerializer.php`, isolate wire-format changes without rewriting packet codecs.

#### Typed Domain Data and Compatibility Support
Nested packet payloads are strongly typed data objects and enums, rather than raw arrays: `src/Data/Type/ItemStack.php`, `src/Data/Type/PlayerAuthInputData.php`, and `src/Enum/ItemStackRequestActionType.php`. Codec cloning/forking support enables derived versions to override mutable codec/serializer dependencies safely: `src/Codec/Support/Forkable.php` and `src/Codec/Support/Forker.php`.

#### Runtime and External Boundaries
The runtime is modern PHP distributed through Composer (`composer.json`) and intended to be virion-compatible with PocketMine-MP. Axiom does not own sockets, sessions, persistence, or external cloud services; the integrating Minecraft server/proxy supplies transport buffers, routes packets, and applies decoded models. Its external interoperability boundary is the Minecraft Bedrock binary protocol.

Main entry points: [`src/Codec/Codec.php`](https://github.com/nicholass003/axiom/blob/master/src/Codec/Codec.php) (Codec Contract), [`src/Version/Protocol/Protocol844.php`](https://github.com/nicholass003/axiom/blob/master/src/Version/Protocol/Protocol844.php) (Layered Protocol Maps), [`src/Codec/CodecBuilder.php`](https://github.com/nicholass003/axiom/blob/master/src/Codec/CodecBuilder.php) (Codec Builder), [`src/Axiom.php`](https://github.com/nicholass003/axiom/blob/master/src/Axiom.php) (Axiom)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_axiom["Axiom<br/>library entry<br/>[Axiom.php]"]
end

subgraph group_versions["Protocol Versions"]
  node_protocol_version["Protocol Version<br/>identifier"]
  node_protocol_contract["Protocol Contract<br/>interface"]
  node_protocol_maps["Layered Protocol Maps<br/>[Protocol844.php]"]
end

subgraph group_codecs["Codec System"]
  node_codec_builder["Codec Builder<br/>dispatcher<br/>[CodecBuilder.php]"]
  node_codec["Codec Contract<br/>interface<br/>[Codec.php]"]
  node_codec_context["Codec Context<br/>[CodecType.php]"]
  node_baseline_codecs["v844 Codec Baseline<br/>wire codecs"]
  node_overrides["Version Codec Overrides<br/>wire codecs<br/>[StartGameCodec.php]"]
end

subgraph group_model["Packet Model"]
  node_packets["Packet Models<br/>semantic models<br/>[Packet.php]"]
  node_packet_ids["Packet IDs<br/>identifiers<br/>[PacketIds.php]"]
  node_packet_example["Start Game Packet<br/>packet model"]
  node_domain_data["Typed Payload Data<br/>data objects<br/>[ItemStack.php]"]
end

subgraph group_shared["Shared Serialization"]
  node_serializers["Shared Serializers<br/>binary subformats"]
  node_serializer_overrides["Serializer Overrides<br/>version overrides"]
  node_forking["Codec Forking<br/>compatibility support<br/>[Forker.php]"]
end

node_host["Server / Proxy Host<br/>integrator"]
node_bedrock{{"Bedrock Binary Protocol<br/>external protocol"}}

node_host -->|"selects protocol"| node_axiom
node_axiom -->|"accepts"| node_protocol_version
node_axiom -->|"returns"| node_codec_builder
node_protocol_version -->|"selects"| node_protocol_maps
node_protocol_contract -->|"implemented by"| node_protocol_maps
node_protocol_maps -->|"maps IDs to"| node_baseline_codecs
node_protocol_maps -->|"overrides with"| node_overrides
node_protocol_maps -.->|"forks dependencies"| node_forking
node_codec_builder -->|"looks up by"| node_packet_ids
node_codec_builder -->|"resolves"| node_codec
node_baseline_codecs -->|"implements"| node_codec
node_overrides -->|"implements"| node_codec
node_baseline_codecs -->|"uses"| node_serializers
node_overrides -->|"uses"| node_serializer_overrides
node_serializer_overrides -.->|"replaces parts of"| node_serializers
node_codec -->|"uses"| node_codec_context
node_codec -->|"decodes / encodes"| node_packets
node_packets -->|"includes"| node_packet_example
node_packets -->|"contains"| node_domain_data
node_host -->|"invokes with buffers"| node_codec_builder
node_codec -->|"reads / writes"| node_bedrock

click node_axiom "https://github.com/nicholass003/axiom/blob/master/src/Axiom.php"
click node_protocol_version "https://github.com/nicholass003/axiom/blob/master/src/Version/ProtocolVersion.php"
click node_protocol_contract "https://github.com/nicholass003/axiom/blob/master/src/Version/Protocol/ProtocolInterface.php"
click node_protocol_maps "https://github.com/nicholass003/axiom/blob/master/src/Version/Protocol/Protocol844.php"
click node_codec_builder "https://github.com/nicholass003/axiom/blob/master/src/Codec/CodecBuilder.php"
click node_codec "https://github.com/nicholass003/axiom/blob/master/src/Codec/Codec.php"
click node_codec_context "https://github.com/nicholass003/axiom/blob/master/src/Codec/CodecType.php"
click node_overrides "https://github.com/nicholass003/axiom/blob/master/src/Codec/v898/StartGameCodec.php"
click node_packets "https://github.com/nicholass003/axiom/blob/master/src/Packet/Packet.php"
click node_packet_ids "https://github.com/nicholass003/axiom/blob/master/src/Packet/PacketIds.php"
click node_packet_example "https://github.com/nicholass003/axiom/blob/master/src/Packet/StartGamePacket.php"
click node_domain_data "https://github.com/nicholass003/axiom/blob/master/src/Data/Type/ItemStack.php"
click node_serializers "https://github.com/nicholass003/axiom/blob/master/src/Codec/Common/Serializer/NetworkNbtSerializer.php"
click node_serializer_overrides "https://github.com/nicholass003/axiom/blob/master/src/Codec/v944/Serializer/LevelSettingsSerializer.php"
click node_forking "https://github.com/nicholass003/axiom/blob/master/src/Codec/Support/Forker.php"

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_axiom toneBlue
class node_protocol_version,node_protocol_contract,node_protocol_maps toneAmber
class node_codec_builder,node_codec,node_codec_context,node_baseline_codecs,node_overrides toneMint
class node_packets,node_packet_ids,node_packet_example,node_domain_data toneRose
class node_serializers,node_serializer_overrides,node_forking toneIndigo
class node_host,node_bedrock toneNeutral
```

## Components

### Public API

- [Axiom](https://github.com/nicholass003/axiom/blob/master/src/Axiom.php): library entry · Creates a codec builder for a requested protocol. · `src/Axiom.php`

### Protocol Versions

Version maps layer overrides over baseline codecs.

- [Protocol Version](https://github.com/nicholass003/axiom/blob/master/src/Version/ProtocolVersion.php): identifier · Supported protocol identifiers. · `src/Version/ProtocolVersion.php`
- [Protocol Contract](https://github.com/nicholass003/axiom/blob/master/src/Version/Protocol/ProtocolInterface.php): interface · Defines a version's codec map contract. · `src/Version/Protocol/ProtocolInterface.php`
- [Layered Protocol Maps](https://github.com/nicholass003/axiom/blob/master/src/Version/Protocol/Protocol844.php): protocol maps · Baseline maps are inherited and changed codecs overridden by later versions. · `src/Version/Protocol/Protocol844.php`

### Codec System

- [Codec Builder](https://github.com/nicholass003/axiom/blob/master/src/Codec/CodecBuilder.php): dispatcher · Resolves packet IDs to version-specific codecs. · `src/Codec/CodecBuilder.php`
- [Codec Contract](https://github.com/nicholass003/axiom/blob/master/src/Codec/Codec.php): interface · Defines packet binary encode and decode operations. · `src/Codec/Codec.php`
- [Codec Context](https://github.com/nicholass003/axiom/blob/master/src/Codec/CodecType.php): context · Carries encode/decode context. · `src/Codec/CodecType.php`
- **v844 Codec Baseline**: wire codecs · Broad base implementation of Bedrock packet layouts.
- [Version Codec Overrides](https://github.com/nicholass003/axiom/blob/master/src/Codec/v898/StartGameCodec.php): wire codecs · Later protocols add or replace changed layouts. · `src/Codec/v898/StartGameCodec.php`

### Packet Model

- [Packet Models](https://github.com/nicholass003/axiom/blob/master/src/Packet/Packet.php): semantic models · Version-neutral application-facing Bedrock messages. · `src/Packet/Packet.php`
- [Packet IDs](https://github.com/nicholass003/axiom/blob/master/src/Packet/PacketIds.php): identifiers · Maps Bedrock message identities for codec dispatch. · `src/Packet/PacketIds.php`
- [Start Game Packet](https://github.com/nicholass003/axiom/blob/master/src/Packet/StartGamePacket.php): packet model · `src/Packet/StartGamePacket.php`
- [Typed Payload Data](https://github.com/nicholass003/axiom/blob/master/src/Data/Type/ItemStack.php): data objects · Nested packet payloads and enums. · `src/Data/Type/ItemStack.php`

### Shared Serialization

- [Shared Serializers](https://github.com/nicholass003/axiom/blob/master/src/Codec/Common/Serializer/NetworkNbtSerializer.php): binary subformats · Reusable serializers for NBT, inventory, and level settings. · `src/Codec/Common/Serializer/NetworkNbtSerializer.php`
- [Serializer Overrides](https://github.com/nicholass003/axiom/blob/master/src/Codec/v944/Serializer/LevelSettingsSerializer.php): version overrides · Isolates subformat changes for derived versions. · `src/Codec/v944/Serializer/LevelSettingsSerializer.php`
- [Codec Forking](https://github.com/nicholass003/axiom/blob/master/src/Codec/Support/Forker.php): compatibility support · Safely clones mutable codec and serializer dependencies. · `src/Codec/Support/Forker.php`

### Other components

- **Server / Proxy Host**: integrator · Supplies transport buffers and consumes packet models.
- **Bedrock Binary Protocol**: external protocol · Binary interoperability boundary.

## Connections

- Server / Proxy Host → Axiom: selects protocol
- Axiom → Protocol Version: accepts
- Axiom → Codec Builder: returns
- Protocol Version → Layered Protocol Maps: selects
- Protocol Contract → Layered Protocol Maps: implemented by
- Layered Protocol Maps → v844 Codec Baseline: maps IDs to
- Layered Protocol Maps → Version Codec Overrides: overrides with
- Layered Protocol Maps → Codec Forking: forks dependencies
- Codec Builder → Packet IDs: looks up by
- Codec Builder → Codec Contract: resolves
- v844 Codec Baseline → Codec Contract: implements
- Version Codec Overrides → Codec Contract: implements
- v844 Codec Baseline → Shared Serializers: uses
- Version Codec Overrides → Serializer Overrides: uses
- Serializer Overrides → Shared Serializers: replaces parts of
- Codec Contract → Codec Context: uses
- Codec Contract → Packet Models: decodes / encodes
- Packet Models → Start Game Packet: includes
- Packet Models → Typed Payload Data: contains
- Server / Proxy Host → Codec Builder: invokes with buffers
- Codec Contract → Bedrock Binary Protocol: reads / writes