Albion Economy Assistant

Tells you what to craft, refine, enchant, haul, and watch in Albion Online — using live market prices, the game's own recipe data, and your character's destiny board progress.

Architecture

Three deployable pieces plus a shared library:

• server/ — Fastify + TypeScript API that also serves the web UI. Stores everything in a shared Postgres. Deployable (Docker) or run locally.
• web/ — Vite + React UI (built and served by the server in production).
• agent/ — a small Windows companion that runs on your gaming PC. It reads game-local data a deployed server can't see (world map, live market orders) and pushes it to the server over an authenticated API. See agent/README.md.
• shared/ — world-map parsing + packet capture, reused by server and agent.

[ Your gaming PC ]                         [ Server (VPS / Forgejo deploy) ]
  Albion Online                              albion-economy container
  agent  ── HTTPS + API key ──►  /api/ingest/*   ├─ serves web UI
  (world map, market orders)                      └─ Postgres (shared, `backend` net)
                                             Nginx Proxy Manager (`proxy` net) → subdomain
  You ── browser ──────────────►  the same server (web UI, API key in browser)

Run locally (single machine)

Needs a Postgres to point at. Quick throwaway one:

docker run -d --name albion-pg -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=albion -p 5432:5432 postgres:16-alpine
export DATABASE_URL=postgres://postgres:pw@127.0.0.1:5432/albion   # PowerShell: $env:DATABASE_URL=...
npm install
npm run gamedata     # download items/recipes into Postgres (first time)
npm run dev          # API on :4310, Vite UI on :5173

Open http://localhost:5173. With no ALBION_API_KEY set, the API is open (fine for localhost).

Deploy (Docker + Forgejo)

The repo ships a Dockerfile, docker-compose.yml, and .forgejo/workflows/deploy.yml.

1. On the host, have your shared Postgres reachable on an external Docker network named backend, and Nginx Proxy Manager on proxy. Create the database: CREATE DATABASE albion;
2. Add Forgejo Actions secrets: DATABASE_URL (e.g. postgres://albion:pw@postgres:5432/albion) and ALBION_API_KEY (a long random string).
3. Push to master (or run the workflow manually). It builds the image and docker compose up -d. The container joins proxy + backend; point an NPM proxy host at albion-economy:4310 and assign your subdomain.
4. First boot auto-downloads and parses game data into Postgres.

Locally you can mirror it: create .env from .env.example, ensure the proxy/backend networks exist, then docker compose up -d.

Security

• ALBION_API_KEY is required in the compose file. Every /api/* route (except /api/health) needs Authorization: Bearer <key> (or ?apiKey=). The web UI prompts for it once and stores it in the browser; the agent sends it from its config.
• Put it behind HTTPS via NPM. For extra safety, keep the subdomain access-listed or behind a private network — an API key is a floor, not a ceiling.

Pages

• Opportunities — ranks every craft/refine/enchant for a city by profit: return rates (city bonuses + focus), station fees, taxes, and recursive buy-vs-craft input decisions. Sort by profit, ROI, or silver-per-focus. Uses your active character profile.
• Travel Planner — safe-only vs all-zones routing (with red/black danger counts) over the real zone graph, plus a haul advisor ranking what to carry between cities by profit per weight.
• Market Watch — price alert rules checked on an interval.
• Character — destiny board profiles (mastery/spec per category) that drive focus costs and taxes.
• Game Sniffer — status of firsthand price capture (when the server runs on your PC; otherwise use the agent).
• Item Browser / Game Data / Settings — recipe explorer, patch-day refresh, server/proxy/game-path config.

Character & game-local data

There is no official API for character progress, so the Character page lets you enter destiny board levels by hand. The agent can also push world-map and market data from your PC. Capturing your own traffic is the SBI-tolerated technique (Albion Data Project style) — read-only, no memory reading, no injection.

After a game patch

• Game Data page → re-download game data (or the agent/npm run gamedata).
• Travel Planner → re-import the world map (or npm run agent -- world).
• Balance constants (return rates, taxes, city bonuses) are editable via PUT /api/economy/config — config, not code.

Tests

npm test           # economy math (vitest); the engine is pure, no DB needed