# ao-data/albiondata-client architecture

> Architecture diagram of the GitHub repository ao-data/albiondata-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ao-data/albiondata-client
- Repository: https://github.com/ao-data/albiondata-client

## Overview

1. This repository builds a single-purpose Go client for Albion Online Data: it runs on a player’s machine, watches local network traffic, extracts game telemetry, and forwards normalized data to upstream collectors. The core architecture is an edge capture pipeline, not an app server.

2. The runtime entrypoint is `albiondata-client.go`, which wires together configuration, packet capture, decoding, dispatch, and uploading. The `client/` package contains most of the live behavior and is the main subsystem boundary.

3. Packet acquisition is the first stage. The client uses libpcap/WinPcap-style capture on the host network interface, with OS-specific interface filtering in `client/net_interface_filter_*.go`. The Windows tree includes vendored capture libraries under `thirdparty/WpdPack`, which is important for the packaging/runtime boundary on that platform.

4. Once packets are captured, the `client/photon/` code parses and deserializes Albion’s Photon protocol traffic. This is where raw UDP payloads become structured operations. The decode path in `client/decode.go` and `client/dispatcher.go` turns those protocol messages into internal events.

5. The event layer is the main application abstraction. Files like `client/event_*.go`, `client/events.go`, and `client/eventtype_string.go` show that the system emits typed domain events such as player online status, redzone/world-map events, skill data, and market-related operations. This is the point where game traffic is translated into Albion-specific semantics.

6. Routing and operation handling are separated from raw decoding. `client/router.go`, `client/operations.go`, and the many `client/operation_*.go` files map Photon operation codes to concrete handlers and return-code logic. This keeps protocol decoding distinct from domain interpretation.

7. There is a persistent-state layer in `client/albion_state.go`, `client/albion_watcher.go`, and `client/offline.go` that likely tracks session/game-state transitions and handles periods when the client is not actively attached to useful traffic. This is the boundary between “capture packets” and “understand whether they matter.”

8. Outbound delivery is handled by uploader implementations in `client/uploader*.go`. The repository supports at least two transport styles: NATS publishing and HTTP-based uploading, with an HTTP proof-of-work variant also present. That makes the downstream boundary explicit: local capture produces events, uploader transports them to shared infrastructure.

9. The `lib/` package contains shared domain models and serialization helpers for the wider Albion Data ecosystem: gold, map, market, market history, skills, bandit events, and NATS-related helpers. This suggests the client is one producer in a distributed data pipeline, and `lib/` defines the payload contracts used across projects.

10. There is a lightweight desktop/runtime UX layer separated from the capture pipeline. `systray/` provides platform-specific tray integration, `notification/` handles OS notifications, and `client/ws_client.go` / `client/ws_hub.go` indicate a real-time internal messaging channel used by the client. These are support subsystems rather than the core data path.

11. Cross-platform concerns are explicit throughout the repo: `*_win.go`, `*_nix.go`, and `*_darw.go` files isolate OS differences; Dockerfiles and shell scripts support builds for Linux, macOS, and Windows; `pkg/nsis` and `winres` package Windows installers/resources. This project is designed as a distributed native binary, not a portable web service.

12. In architecture terms, the main flow is: host network interface → packet capture → Photon decode → operation routing/state tracking → typed Albion events → uploader transport → central NATS/HTTP infrastructure. The main boundaries are OS capture, protocol decoding, domain eventing, and outbound distribution.

Main entry points: [`client/client.go`](https://github.com/ao-data/albiondata-client/blob/master/client/client.go) (Client core), [`client/decode.go`](https://github.com/ao-data/albiondata-client/blob/master/client/decode.go) (Decode), [`client/operations.go`](https://github.com/ao-data/albiondata-client/blob/master/client/operations.go) (Operations), [`client/events.go`](https://github.com/ao-data/albiondata-client/blob/master/client/events.go) (Events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_entry["Entrypoint"]
  node_node_main["Main<br/>go entrypoint"]
end

subgraph group_group_client["Capture pipeline"]
  node_node_client["Client core<br/>runtime coordinator<br/>[client.go]"]
  node_node_config["Config<br/>settings<br/>[config.go]"]
  node_node_capture["Net filter<br/>interface selection"]
  node_node_decode["Decode<br/>[decode.go]"]
  node_node_photon["Photon parse<br/>protocol parser<br/>[parser.go]"]
  node_node_dispatcher["Dispatcher<br/>message router<br/>[dispatcher.go]"]
  node_node_router["Router<br/>op routing<br/>[router.go]"]
  node_node_ops["Operations<br/>handler set<br/>[operations.go]"]
  node_node_state["State<br/>[albion_state.go]"]
  node_node_offline["Offline<br/>disconnect handling<br/>[offline.go]"]
  node_node_events["Events<br/>[events.go]"]
  node_node_uploader["Uploader<br/>delivery layer<br/>[uploader.go]"]
  node_node_http["HTTP upload<br/>transport<br/>[uploader_http.go]"]
  node_node_nats["NATS upload<br/>transport<br/>[uploader_nats.go]"]
end

subgraph group_group_shared["Shared models"]
  node_node_lib["Lib models<br/>shared contracts<br/>[common.go]"]
end

subgraph group_group_platform["Platform glue"]
  node_node_systray(("Tray UI<br/>desktop integration<br/>[systray_others.go]"))
  node_node_notify["Notifications"]
  node_node_wpdpack[("WpdPack<br/>capture dependency<br/>[pcap.h]")]
end

node_node_main -->|"boots"| node_node_client
node_node_client -->|"loads"| node_node_config
node_node_client -->|"selects"| node_node_capture
node_node_client -->|"captures"| node_node_decode
node_node_decode -->|"parses"| node_node_photon
node_node_decode -->|"hands off"| node_node_dispatcher
node_node_dispatcher -->|"routes"| node_node_router
node_node_router -->|"maps to"| node_node_ops
node_node_ops -->|"updates"| node_node_state
node_node_state -.->|"falls back"| node_node_offline
node_node_ops -->|"emits"| node_node_events
node_node_events -->|"publishes"| node_node_uploader
node_node_uploader -->|"implements"| node_node_http
node_node_uploader -->|"implements"| node_node_nats
node_node_events -->|"serializes with"| node_node_lib
node_node_client -.->|"integrates"| node_node_systray
node_node_client -.->|"signals"| node_node_notify
node_node_capture -.->|"windows dep"| node_node_wpdpack

click node_node_main "https://github.com/ao-data/albiondata-client/blob/master/albiondata-client.go"
click node_node_client "https://github.com/ao-data/albiondata-client/blob/master/client/client.go"
click node_node_config "https://github.com/ao-data/albiondata-client/blob/master/client/config.go"
click node_node_capture "https://github.com/ao-data/albiondata-client/blob/master/client/net_interface_filter.go"
click node_node_decode "https://github.com/ao-data/albiondata-client/blob/master/client/decode.go"
click node_node_photon "https://github.com/ao-data/albiondata-client/blob/master/client/photon/parser.go"
click node_node_dispatcher "https://github.com/ao-data/albiondata-client/blob/master/client/dispatcher.go"
click node_node_router "https://github.com/ao-data/albiondata-client/blob/master/client/router.go"
click node_node_ops "https://github.com/ao-data/albiondata-client/blob/master/client/operations.go"
click node_node_state "https://github.com/ao-data/albiondata-client/blob/master/client/albion_state.go"
click node_node_offline "https://github.com/ao-data/albiondata-client/blob/master/client/offline.go"
click node_node_events "https://github.com/ao-data/albiondata-client/blob/master/client/events.go"
click node_node_uploader "https://github.com/ao-data/albiondata-client/blob/master/client/uploader.go"
click node_node_http "https://github.com/ao-data/albiondata-client/blob/master/client/uploader_http.go"
click node_node_nats "https://github.com/ao-data/albiondata-client/blob/master/client/uploader_nats.go"
click node_node_lib "https://github.com/ao-data/albiondata-client/blob/master/lib/common.go"
click node_node_systray "https://github.com/ao-data/albiondata-client/blob/master/systray/systray_others.go"
click node_node_notify "https://github.com/ao-data/albiondata-client/blob/master/notification/notification_win.go"
click node_node_wpdpack "https://github.com/ao-data/albiondata-client/blob/master/thirdparty/WpdPack/Include/pcap.h"

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_node_main toneBlue
class node_node_client,node_node_config,node_node_capture,node_node_decode,node_node_photon,node_node_dispatcher,node_node_router,node_node_ops,node_node_state,node_node_offline,node_node_events,node_node_uploader,node_node_http,node_node_nats toneAmber
class node_node_lib toneMint
class node_node_systray,node_node_notify,node_node_wpdpack toneRose
```

## Components

### Entrypoint

Process bootstrap and wiring

- [Main](https://github.com/ao-data/albiondata-client/blob/master/albiondata-client.go): go entrypoint · Wires config, capture, decode, and upload. · `albiondata-client.go`

### Capture pipeline

Packet capture, decode, state, and delivery

- [Client core](https://github.com/ao-data/albiondata-client/blob/master/client/client.go): runtime coordinator · Main subsystem boundary for live capture behavior. · `client/client.go`
- [Config](https://github.com/ao-data/albiondata-client/blob/master/client/config.go): settings · Loads and applies runtime configuration. · `client/config.go`
- [Net filter](https://github.com/ao-data/albiondata-client/blob/master/client/net_interface_filter.go): interface selection · Chooses capture-capable interfaces per OS. · `client/net_interface_filter.go`
- [Decode](https://github.com/ao-data/albiondata-client/blob/master/client/decode.go): packet decode · Turns captured packet data into structured messages. · `client/decode.go`
- [Photon parse](https://github.com/ao-data/albiondata-client/blob/master/client/photon/parser.go): protocol parser · Parses Albion Photon protocol payloads. · `client/photon/parser.go`
- [Dispatcher](https://github.com/ao-data/albiondata-client/blob/master/client/dispatcher.go): message router · Bridges decoded protocol traffic into internal handling. · `client/dispatcher.go`
- [Router](https://github.com/ao-data/albiondata-client/blob/master/client/router.go): op routing · Maps operation codes to handlers and return-code logic. · `client/router.go`
- [Operations](https://github.com/ao-data/albiondata-client/blob/master/client/operations.go): handler set · Concrete operation handlers for game requests. · `client/operations.go`
- [State](https://github.com/ao-data/albiondata-client/blob/master/client/albion_state.go): session state · Tracks Albion session and game-state transitions. · `client/albion_state.go`
- [Offline](https://github.com/ao-data/albiondata-client/blob/master/client/offline.go): disconnect handling · Handles periods without useful traffic attachment. · `client/offline.go`
- [Events](https://github.com/ao-data/albiondata-client/blob/master/client/events.go): domain events · Typed Albion-specific events emitted by the client. · `client/events.go`
- [Uploader](https://github.com/ao-data/albiondata-client/blob/master/client/uploader.go): delivery layer · Abstracts outbound transport to upstream collectors. · `client/uploader.go`
- [HTTP upload](https://github.com/ao-data/albiondata-client/blob/master/client/uploader_http.go): transport · HTTP-based event delivery path. · `client/uploader_http.go`
- [NATS upload](https://github.com/ao-data/albiondata-client/blob/master/client/uploader_nats.go): transport · Publishes events onto NATS infrastructure. · `client/uploader_nats.go`

### Shared models

Reusable domain contracts and helpers

- [Lib models](https://github.com/ao-data/albiondata-client/blob/master/lib/common.go): shared contracts · Common payload models and serialization helpers. · `lib/common.go`

### Platform glue

Desktop integration and OS-specific packaging

- [Tray UI](https://github.com/ao-data/albiondata-client/blob/master/systray/systray_others.go): desktop integration · Native tray integration for the local client. · `systray/systray_others.go`
- [Notifications](https://github.com/ao-data/albiondata-client/blob/master/notification/notification_win.go): os notifications · Desktop notification support per platform. · `notification/notification_win.go`
- [WpdPack](https://github.com/ao-data/albiondata-client/blob/master/thirdparty/WpdPack/Include/pcap.h): capture dependency · Windows capture headers and libraries bundled for runtime packaging. · `thirdparty/WpdPack/Include/pcap.h`

## Connections

- Main → Client core: boots · Entrypoint creates the live client runtime.
- Client core → Config: loads · Client reads runtime settings.
- Client core → Net filter: selects · Client chooses capture interfaces.
- Client core → Decode: captures · Capture pipeline feeds packet decode.
- Decode → Photon parse: parses · Photon parser deserializes protocol payloads.
- Decode → Dispatcher: hands off · Decoded messages are dispatched for interpretation.
- Dispatcher → Router: routes · Dispatcher forwards operations to routing logic.
- Router → Operations: maps to · Operation codes resolve to concrete handlers.
- Operations → State: updates · Handlers affect tracked game/session state.
- State → Offline: falls back · State layer handles offline or detached periods.
- Operations → Events: emits · Domain handlers produce Albion-specific events.
- Events → Uploader: publishes · Events are forwarded to outbound delivery.
- Uploader → HTTP upload: implements · One transport is HTTP-based upload.
- Uploader → NATS upload: implements · One transport is NATS publishing.
- Events → Lib models: serializes with · Shared models define payload contracts.
- Client core → Tray UI: integrates · Client exposes tray-based desktop control.
- Client core → Notifications: signals · Client can surface desktop notifications.
- Net filter → WpdPack: windows dep · Windows capture path depends on bundled WpdPack.
