# 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
```