How ao-data/albiondata-client works
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.go Client core · decode.go Decode · operations.go Operations · events.go Events
Components 19
Entrypoint
Process bootstrap and wiring
- Main · Wires config, capture, decode, and upload.
albiondata-client.go
Capture pipeline
Packet capture, decode, state, and delivery
- Client core · Main subsystem boundary for live capture behavior.
client/client.go - Config · Loads and applies runtime configuration.
client/config.go - Net filter · Chooses capture-capable interfaces per OS.
client/net_interface_filter.go - Decode · Turns captured packet data into structured messages.
client/decode.go - Photon parse · Parses Albion Photon protocol payloads.
client/photon/parser.go - Dispatcher · Bridges decoded protocol traffic into internal handling.
client/dispatcher.go - Router · Maps operation codes to handlers and return-code logic.
client/router.go - Operations · Concrete operation handlers for game requests.
client/operations.go - State · Tracks Albion session and game-state transitions.
client/albion_state.go - Offline · Handles periods without useful traffic attachment.
client/offline.go - Events · Typed Albion-specific events emitted by the client.
client/events.go - Uploader · Abstracts outbound transport to upstream collectors.
client/uploader.go - HTTP upload · HTTP-based event delivery path.
client/uploader_http.go - NATS upload · Publishes events onto NATS infrastructure.
client/uploader_nats.go
Shared models
Reusable domain contracts and helpers
- Lib models · Common payload models and serialization helpers.
lib/common.go
Platform glue
Desktop integration and OS-specific packaging
- Tray UI · Native tray integration for the local client.
systray/systray_others.go - Notifications · Desktop notification support per platform.
notification/notification_win.go - WpdPack · Windows capture headers and libraries bundled for runtime packaging.
thirdparty/WpdPack/Include/pcap.h
Connections 18
- 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.