albion/docs/AFM-PARITY-ROADMAP.md

# Albion Free Market parity — roadmap + first build phase

## Context

We like [albionfreemarket.com](https://albionfreemarket.com) (AFM) and want our app to reach **as
much feature parity as possible over time**. This document is the durable roadmap: a complete
catalog of AFM's features (what each does, how it's built, what data it needs, our current
status), plus a concrete implementation plan for the **first phase** — the trading/pricing
cluster (quality-aware pricing → price history/EMV → arbitrage flipper → Black Market flipper).

Keep this file updated as features land (flip the status markers).

AFM and our app share the same data backbone: the **Albion Data Project (AODP)** — crowdsourced
sniffer clients upload market orders (and price history). So almost everything AFM does is
achievable for us; the gaps are breadth of tools, price **history**, **EMV** (a fair-value
baseline from history), **Black Market flipping**, and account/portfolio features.

Legend — **Us:** ✅ have · 🟡 partial · ❌ missing.

---

## Complete AFM feature catalog + our status

### 1. Market data & analysis
- **Price Check** — live prices per item across cities/servers. Data: AODP prices. **Us: ✅** (Market Data).
- **Price History Charts** — trend up to 180 days, daily points. Data: AODP `/history`. **Us: ❌**.
- **EMV (Estimated Market Value)** — statistical fair-value baseline from history to judge over/under-pricing (their "AI" = smoothed/median of historical avg price). Data: history. **Us: ❌**.
- **Top Traded Items** — most-traded by volume/silver, filterable. Data: history `item_count`. **Us: ❌**.
- **Quality-aware pricing** — prices per quality 1–5. **Us: 🟡** (storage, AODP fetch, sniffer, overrides, watch rules, Market page all q1–5; **only the economy engine hardcodes q1** — `service.ts` `WHERE quality = 1`).
- **CSV export** of market data. **Us: ❌**.

### 2. Crafting & production
- **Full Craft/Refine calculator** — RRR + focus + journals + food + quality rerolls, auto-loads prices, per-material breakdown. **Us: 🟡** (we have RRR, focus, taxes, station fees, recursive buy-vs-craft, and rank *all* recipes at once; missing journals, food/nutrition modeling, quality-reroll odds, single-item deep-dive view).
- **Simple Craft calculator** + shareable link. **Us: 🟡** (Opportunities ranker + URL-synced filters; no dedicated single-item quick view).
- **RRR calculator** — return rate by city/spec. **Us: ✅** (engine + Character page).
- **Farm & Breed calculator** — crops/animals/island yield + profit. Data: farm/seed/offspring tables. **Us: ❌**.
- **Journals calculator** — fame→journal fill happiness + profit. Data: journal items + fame values. **Us: ❌**.
- **Transmutation** — cost to convert tier/enchant. Data: transmutation recipes. **Us: ❌**.

### 3. Trading & flipping
- **Market Flipper** — buy-order vs sell-order arbitrage within/between cities. Data: AODP buy+sell + freshness. **Us: ❌**.
- **Black Market Flipper** — royal sell order → Black Market buy order, minus tax + transport (Smuggler's Network distance fee); includes **upgrade flips** (buy low-enchant + runes to match a higher-enchant BM buy order) and **private flips** (use only your own sniffed orders). Data: AODP incl. BM buy orders (we already fetch these). **Us: ❌** (BM is a tracked city already; no flip logic).
- **EMV Flipper** — orders priced far from EMV (bargains / overpriced). Data: EMV. **Us: ❌**.
- **Trade Routes finder** — profitable multi-hop trading sequences. **Us: 🟡** (2-city Haul Advisor exists; no multi-hop).
- **Trade Calculator** — transport route profit given weight/fees. **Us: 🟡** (haul by weight; no fee/teleport model).
- **Upgrade Calculator** — buy-ready vs buy-low+upgrade. Data: upgrade recipes (we parse them). **Us: 🟡** (engine has upgrade recipes; no dedicated UI).

### 4. Character & knowledge
- **Your Specs** — Destiny Board spec tracker, uploaded by the data client. **Us: 🟡** (manual Character page; sniffer auto-fill of specs not wired — event codes TBD from a live capture).
- **Item Power (IP)** — gear IP from tier/enchant/quality/masteries + price-by-IP. Data: IP formula + item stats (not in our current dump). **Us: ❌**.
- **Repair Cost calculator** — repair silver by item/quality. Data: item value + repair formula. **Us: ❌**.
- **Teleport Calculator** — fast-travel silver cost between cities by weight. Data: teleport fee formula. **Us: 🟡** (routes exist; no silver cost).
- **Mounts** — mount stats/spells/pricing browser. **Us: ❌**.
- **Albion Journal** — achievements browser. **Us: ❌**.
- **Articles & Tutorials** — guides. **Us: ❌** (out of scope).

### 5. Maps & navigation
- **World Map / Albion Maps** — interactive zone map, markers, resources, POIs. **Us: 🟡** (zone graph + text routing/directions; no visual map).
- **Pathfinder / Routes** — travel time with waypoints + mount speeds. **Us: 🟡** (hop-count routing; no time/mount-speed).
- **Roads of Avalon** — ROA network routing with exit tracking (time-limited portals). **Us: ❌** (deliberately excluded from routing today).
- **Teleport routes** — see Teleport Calculator above.

### 6. PvP / meta (separate domain — needs kill/loot data, lowest priority)
- **Builds / Build Bundles** — create/share gear+skill builds. **Us: ❌**.
- **Meta Items** — item popularity from PvP kill data. **Us: ❌**.
- **Meta Builds** — full gear sets from recorded fights. **Us: ❌**.
- **Loot Logger** — record PvE/PvP loot, value with EMV. **Us: ❌**.
- **Awakened Items marketplace + Awakened Calculator** — awakened weapon trait/cost modeling. **Us: ❌**.

### 7. Portfolio / accounts / QoL
- **Portfolio Tracker** — holdings, transactions, FIFO stock pricing, P&L. Data: user-recorded trades. **Us: ❌**.
- **Your Flips / Your Crafts history** — historical flip/craft tracking with charts. **Us: ❌**.
- **Accounts + subscription** (Patreon) gating premium features. **Us: ❌** (we have single API key, no multi-user accounts).
- **Menu favorites, themes, i18n (localized item names), URL sharing.** **Us: 🟡** (URL sharing via routing done; favorites/themes/i18n missing).
- **Data Client** (desktop app uploading prices + specs + loot). **Us: 🟡** (our agent uploads prices + world map; no spec/loot upload yet).

---

## Approved first phase — trading & pricing cluster

Build order below is dependency-ordered. Reuse existing patterns: AODP client chunk/throttle
(`market/client.ts` `fetchPrices`), `upsertPriceRows` bulk-upsert, backend cache + cooldown
(`cache.ts`, `market/service.ts`), freshness ages, `economy/config.ts` for editable fees/taxes,
and the pure engine in `economy/engine.ts`.

### Part A — Quality-aware pricing (foundation)
- `economy/service.ts` `buildProvider(city)` → `buildProvider(city, quality)`: load the chosen
  quality's price map with **fallback to q1** (resources have no quality; equipment output does).
  Drop the hardcoded `WHERE quality = 1`.
- `RankRequest` gains `quality?` (default 1); thread through `rankOpportunities`.
- `OpportunitiesPage.tsx`: quality selector (1–5), URL-synced like other filters.
- Files: `server/src/economy/service.ts`, `server/src/routes/economy.ts`, `web/src/pages/OpportunitiesPage.tsx`.

### Part B — Price history + EMV + Top Traded
- `market/client.ts`: add `fetchHistory` → AODP `GET /api/v2/stats/history/{items}?date&locations&qualities&time-scale=24`
  (daily). Same chunk/throttle/proxy/`AodpUnreachableError` handling. **Confirm response shape
  defensively on first run** (`[{location,item_id,quality,data:[{item_count,avg_price,timestamp}]}]`).
- DB: new `price_history(item, city, quality, ts, avg_price, item_count)` PK(item,city,quality,ts);
  new `market_emv(item, city, quality, emv, updated_at)`. Add to schema + `ALTER … IF NOT EXISTS`.
- `market/service.ts`: history refresh job (mirrors price refresh + cooldown); EMV compute =
  item_count-weighted median/avg of last N days' `avg_price`; store to `market_emv`. Merge `emv`
  into `getPricesForItem`.
- Endpoints (`routes/market.ts`): `POST /api/market/history/refresh`, `GET /api/market/history/:item`
  (series for charts), `GET /api/market/top-traded?days=` (sum item_count).
- UI: inline **SVG** line chart on the Market Data item view (no external libs — CSP), with an EMV
  reference line; a "Top Traded" section/tab.

### Part C — Arbitrage flipper (general)
- New `economy/flip.ts` (pure): given prices for item×city×quality, find buy-low/sell-high:
  within-city (sell_min→buy_max) and cross-city (buy_min city A → sell to buy_max city B), minus
  sales tax (premium-aware) and transport (weight-based). **False-positive guards:** only orders
  within a freshness window (reuse cooldown/age), and an optional **EMV sanity filter** (skip when
  a price deviates from EMV beyond a configurable %).
- `routes/market.ts`: `POST /api/market/flips` (cities, tiers, minProfit, useEmvFilter) → rows
  {item, buyCity, buyPrice, sellCity, sellPrice, tax, transport, profit, roi, profitPer100kg, ages}.
- UI: new **Flipper** tab (route `/flipper`, URL-synced filters), sortable table.

### Part D — Black Market flipper
- Specialize Part C: sell side = Black Market `buy_price_max`; buy side = royal/Caerleon
  `sell_price_min`; net = `bmBuy*(1-salesTax) - buyPrice - transportToBM` (BM instant-sell = sales
  tax only, no listing fee). Uses existing `market_prices` — **no new fetch**.
- Transport model: add editable `transportFees` to `economy/config.ts` (per source city →
  Caerleon/BM, silver per 100kg or flat; approximate, user-tunable — Smuggler's Network fees shift).
- **Upgrade flips:** reuse engine upgrade recipes + `acquisitionCost` to compare buy-low+runes vs a
  higher-enchant BM buy order.
- UI: "Black Market" mode in the Flipper tab (transport-fee column, upgrade-flip toggle).

---

## Backlog (later phases, toward fuller parity)

Ordered roughly by value for a solo economy player:
1. Single-item **Craft deep-dive** view (food/nutrition, journals, quality-reroll odds).
2. **Trade Routes** (multi-hop) + **Teleport/transport fee** model + travel time & mount speed.
3. **Portfolio / Your Flips / Your Crafts** history (record user trades; needs a light user model).
4. **Farm & Breed**, **Journals**, **Transmutation** calculators (need extra game-data tables).
5. **Item Power / Repair cost** (need item stat + formulas; may require a richer data dump).
6. **Sniffer spec auto-fill** (finish destiny-board event mapping) + agent **loot upload**.
7. **Visual world map**, **Roads of Avalon** routing.
8. QoL: favorites, themes, i18n item names, CSV export.
9. PvP/meta (Builds, Meta Items/Builds, Loot Logger, Awakened) — only if we expand beyond economy.
10. Multi-user **accounts** (only if this is ever shared beyond a single user).

---

## Verification (for the first phase)

- **Unit tests** (vitest, pure funcs): flip math (tax/transport/ROI/profit-per-100kg), EMV
  computation, quality-aware provider fallback. Add to `server/src/economy/*.test.ts`.
- **End-to-end** against a throwaway Postgres: seed prices incl. Black Market buy orders + a few
  history rows; verify quality-aware ranking, `/history` series, EMV values, `/flips` and Black
  Market flips, and cache invalidation on price writes.
- **Manual** (needs VPN): refresh history for a few items → view chart + EMV; run the Black Market
  flipper and cross-check one flip's numbers against AFM/albiononline2d.

## Notes / unknowns
- AODP `/history` response shape parsed defensively; adjust on first live run.
- Smuggler's/transport fees are approximate → keep in editable config, show freshness so users
  sanity-check.
- Black Market buy orders depend on community scans and can be sparse/stale → always surface age.

---

## How AFM is built (reference notes)

- **Data client**: desktop/mobile apps that sniff network traffic and upload market orders (and
  specs/loot) to AODP + AFM. Directly analogous to our `agent/`.
- **Order freshness**: AFM treats sell orders as valid ~60 min, buy orders ~30 min, to reduce
  false positives from already-consumed orders. We have `fetched_at` + a cooldown we can reuse.
- **Black Market**: has **buy orders** scanned by players into AODP under location "Black Market"
  (id 3003). We already fetch it as a tracked city — the flip finder just needs to use it.
- **EMV**: presented as "AI fair value"; functionally a smoothed/median baseline over historical
  average prices, used to flag over/under-priced orders and filter fake/stale flips.
- **Homepage scale (for context)**: ≈106k users; 212.8B flipper profit + 37.8B craft profit
  reported generated; 4% sales-tax figure referenced in their impact numbers.