albion/docs/AFM-PARITY-ROADMAP.md

Albion Free Market parity — roadmap + first build phase

Context

We like 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.