337dac78ba
All checks were successful
Deploy / deploy (push) Successful in 3m58s
- Extract world-parse + packet capture into @albion/shared (reused by server and a new standalone agent workspace). - Migrate the data layer from SQLite/better-sqlite3 to shared Postgres (async pg with a ?->$n helper; economy engine preloads the item/recipe graph so its sync recursion still works). - API-key auth (ALBION_API_KEY) on all /api routes except health; web UI sends it via a fetch wrapper + key-entry gate; server serves the built UI with a path-traversal-safe static handler (drops @fastify/static). - Windows companion agent: pushes world map + captured market orders to /api/ingest/*; runs on the gaming PC where the game traffic lives. - Docker + docker-compose (external proxy + backend networks for Nginx Proxy Manager and shared Postgres) and a Forgejo deploy workflow. - Validated end-to-end against Postgres 16 and a full compose run. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
76 lines
4.7 KiB
Markdown
76 lines
4.7 KiB
Markdown
# 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
|
|
```
|