GearBox/.planning/milestones/v2.3-ROADMAP.md

Milestone v2.3: Global & Social Ready

Status: ✅ SHIPPED 2026-04-19 Phases: 32-34 Total Plans: 18

Overview

Made GearBox work for a global audience. Setup sharing with fine-grained visibility control, a full multi-currency pricing system with ECB exchange rates and community price aggregation, and an i18n foundation with English + German translations — all delivered in 6 days across 3 phases and 18 plans.

Phases

Phase 32: Setup Sharing System

Goal: Setup owners can toggle visibility between private, link-shared, and public, with schema designed for future likes, friends, and collaborative editing Depends on: Phase 28 (profiles working) Plans: 4 plans

Plans:

• 32-01-PLAN.md — Schema migration (isPublic to visibility) + shares table + full-stack update
• 32-02-PLAN.md — Share link service, API routes, and short URL redirect
• 32-03-PLAN.md — Share modal UI component with visibility picker and link management
• 32-04-PLAN.md — Shared setup viewer with token detection and read-only mode

Details:

• visibility text column (private/link/public) replaces isPublic boolean on setups table
• shares table with token, permission, expiresAt, userId, revokedAt — schema future-proofed for person-specific shares and write permissions
• Share tokens use randomBytes(16).toString("base64url") — 128-bit entropy, URL-safe
• Visibility→private deactivates share links; switching back reactivates non-expired ones
• /s/:token short URL redirects to /setups/:id?share=token; /api/shared/:token returns setup data without auth
• ShareModal replaces old globe toggle — Google Docs-style with visibility picker + link management
• Three-way data source in setup detail page: share token > authenticated owner > public viewer

Phase 33: Currency System

Goal: Users can select their preferred currency (USD/EUR/GBP) and all prices display accordingly — full market-aware pricing system with community price data Depends on: Phase 32 Plans: 6 plans

Plans:

• 33-01-PLAN.md — Schema (market_prices, community_prices tables) + currency conversion service
• 33-02-PLAN.md — Database migration generation and push
• 33-03-PLAN.md — Market prices API, exchange rates endpoint, item/candidate currency context
• 33-04-PLAN.md — Community price service (ownership validation, median aggregation) + setup totals
• 33-05-PLAN.md — Formatter evolution, market/currency selector, auto-suggestion, conversion toggle
• 33-06-PLAN.md — Catalog detail market prices, comparison table normalization, MCP tool updates

Details:

• market_prices and community_prices tables with unique constraints
• priceCurrency column on items; foundPriceCents/Currency/Date on thread_candidates
• Exchange rates fetched daily from ECB via frankfurter.app with 24h module-level cache
• Community price aggregation: PERCENTILE_CONT(0.5) median with 3-report minimum, ownership-validated submissions
• Converted prices labeled with ~ prefix and dual display format
• CurrencyContext interface (currency, market, showConversions) from useCurrency()
• Market-aware MSRP section on catalog detail page with collapsible "Other Markets"

Phase 34: i18n Foundation

Goal: Translation framework in place with string extraction, locale-aware formatting, and at least English + one additional language Depends on: Phase 33 Plans: 8 plans

Plans:

• 34-01-PLAN.md — i18next + react-i18next setup, English namespace JSON files
• 34-02-PLAN.md — German translations for all 6 namespaces
• 34-03-PLAN.md — Component wiring (collection, threads, setups namespaces)
• 34-04-PLAN.md — Settings and onboarding namespace wiring
• 34-05-PLAN.md — Language picker component in settings
• 34-06-PLAN.md — Locale-aware formatting (dates, numbers)
• 34-07-PLAN.md — catalog namespace for global-items/discover page
• 34-08-PLAN.md — Final wiring and verification

Details:

• react-i18next with i18next-browser-languagedetector
• 6 namespaces: common, collection, threads, setups, onboarding, settings (+ catalog added in 34-07)
• Detection order: localStorage (key: gearbox-language) then navigator.language
• Static lookup tables (icons, CSS) kept at module level; only label strings moved inside components for t() access
• English + German locales, language picker in settings

---

Milestone Summary

Key Decisions:

• isPublic boolean replaced with visibility text column (private/link/public) — RESOLVED
• shares table future-proofed for person-specific shares and write permissions — RESOLVED
• Share tokens: randomBytes(16).toString("base64url") — 128-bit entropy, URL-safe — RESOLVED
• Visibility→private deactivates share links; switching back reactivates non-expired ones — RESOLVED
• EUR as default price currency matching existing data assumption — RESOLVED
• Module-level caching for exchange rates (simple, effective for single-process) — RESOLVED
• Community price aggregation uses PERCENTILE_CONT(0.5) with 3-report minimum — RESOLVED
• Detection order for locale: localStorage first, then navigator.language — RESOLVED
• defaultNS is common; escapeValue: false (React handles XSS) — RESOLVED

Issues Resolved:

• isPublic boolean → visibility text migration handled with data migration SQL
• Dynamic import in setup.service.ts to avoid circular dependency with share.service.ts

Issues Deferred:

• ComparisonTable currency normalization (hooks available, deferred pending real multi-currency test data)
• MCP tool currency updates (existing priceCents responses work with currency context client-side)
• E2E tests rewrite for OIDC auth (backlog 999.1)

Technical Debt Incurred:

• 6 pending todos deferred to v2.4 (cursor pointers, image loading, auth redirect, add-candidate modal)

Known deferred items at close: 6 (see STATE.md Deferred Items)

---

For current project status, see .planning/ROADMAP.md