A self-hosted Progressive Web App for cataloging, analyzing, and sharing a personal coin collection.

Note: This application is 100% vibe coded. It exists for the author to learn and experiment with GitHub Copilot CLI.

Aurearia is a self-hosted, full-featured Progressive Web App for managing a personal coin collection end-to-end, with an emphasis on ancient and historical coins. Catalog, value, analyze, organize, and share your coins with powerful AI-assisted tools, offline access, and community features — all on your own server.

For collectors who want:

• 🏛️ Detailed numismatic records with provenance, images, and structured references
• 🤖 AI-powered analysis of coin photos (Claude or self-hosted Ollama)
• 🔍 Smart discovery tools for finding, tracking, and monitoring coins
• 📊 Rich portfolio analytics with value trends and gap analysis
• 🤝 Social features to follow collectors and share curated collections
• 📱 Install as a PWA; offline read access on mobile and desktop
• 🔒 Complete control of data; runs entirely on your infrastructure

Built for a single collector plus invited friends. Not a marketplace, SaaS, or reference database replacement. If you expose it outside a trusted home network, follow the public-facing hardening checklist in docs/deployment.md: TLS, reverse-proxy security headers, trusted proxy IP handling, invite/closed registration, private agent networking, backups, and monitoring are required.

Product vision, personas, and detailed requirements in docs/prd.md. This README highlights features; see documentation links below for deep dives.

Organize coins with rich metadata: denomination, ruler, material, weight, inscriptions, grades, provenance, images, and free-text notes. Flexible filtering, full-text search, random shuffle with deterministic seed, and swipe/grid gallery views. Learn more →

Quick Capture — Save sparse mobile/PWA intake drafts with photos or notes, resume/edit/discard them later, and explicitly promote a completed draft into exactly one normal collection coin without affecting collection, wishlist, sold, stats, or health counts before promotion. Learn more →

Obverse & Reverse Analysis — Upload coin photos for AI inspection with condition assessment, grade estimates, historical context, and market insights. Supports Anthropic Claude or self-hosted Ollama vision models.

Deep Analysis — Optionally send obverse/reverse photos, notes, and ephemeral hint images through a resumable background workflow. The router combines image evidence with available authority providers, streams replayable progress, and produces a cited report plus an editable proposal that is never written without confirmation. Numista and Nomisma-backed OCRE evidence are supported; NGC is link-out only and automated RPC research is paused. Learn more →

Nomisma Authority Linking — Admins can explicitly reconcile global mint locations to Nomisma.org concepts with visible CC BY 4.0 attribution; private/user-defined mints remain local.

Coin Agent — Ask one chat surface to search dealer listings, find shows, analyze portfolio questions, answer collection questions such as missing metadata, and save useful answers as markdown Notes after review. Learn more →

AI Coin Search — Chat with an agent to find real dealer listings matching your description. Imports structured results with images, metadata, prices, and candidate catalog references.

Coin Lookup — Take or upload photos at a show to identify a coin or NGC Ancients slab. The app extracts NGC certification numbers, links to official NGC verification, enriches non-NGC lookups with Numista matches, and can save results to your wish list or collection. Learn more →

Wish List — Track coins you want with automatic availability checking, saved search alerts, AI search, price tracking, and one-click purchase-to-collection conversion. Learn more →

Auction Tracking — Monitor NumisBids and CNG Auctions lots with provider-aware tracking: CNG supports richer hosted-auction sync and outcome detection where available, while NumisBids supports watchlist/import tracking with manual won/lost and max-bid updates. Learn more →

Collection Statistics — Dashboard and subviews for portfolio value trends, category/material/grade distributions, top coins by value, mint maps, timeline, investment breakdown, Emperor Tracker, and health scorecards. Learn more →

Collection Time Machine — Scrub a timeline to see the collection exactly as it stood on any past date: what you owned, what it was worth then, and how it was distributed. Reconstructed from purchase/sold dates and recorded valuation history, and explicit about which figures rest on a real valuation versus a purchase-price fallback. Learn more →

Coin Sets — Organize coins into standard, goal, smart, or human-reviewed Agentic sets with tray presentation, completion tracking, snapshots, and comparison tools. Learn more →

Follow Collectors — Send follow requests, view follower galleries, leave comments, rate coins 1-5 stars.

Profiles — Customize avatar, bio, and privacy settings. Toggle public/private profile with follower management.

Showcases — Create curated public subsets with shareable URLs (e.g., /s/favorite-denarii). Learn more →

PWA Installation — Install on iOS, Android, desktop (Chrome/Edge/Brave). Standalone app window, no browser UI.

Offline Read Access — Service worker caches collection data and images for offline browsing. Writes require an active network connection.

Mobile Gestures — Swipe gallery, pull-to-refresh, camera capture, touch-optimized controls. Learn more →

Multiple Auth Methods — JWT + refresh tokens, WebAuthn passkeys (FIDO2), OIDC login/account linking, and API keys for programmatic access.

External Tool Server — Expose read-only collection to external AI clients (OpenWebUI, LibreChat) via OpenAPI with scoped API keys and two-phase commit for writes.

Fine-Grained Privacy — Public/private profiles, per-coin privacy toggle, role-based admin access. Learn more →

Structured Catalog References — Formally link coins to RIC, RPC, SNG, Numista catalogs. Activity Journals — Timestamped logs per coin (cleaned, graded, displayed). PDF Export — Generate insurance catalogs with photos, provenance, valuations. OCR Text Extraction — Extract text from store cards and certificates. Daily Featured Coins — Automated scheduler to rediscover forgotten coins. Image Operations — Background removal, circle clipping, automatic extraction. Bulk Operations — Multi-select for batch tagging, status changes, exports. Configurable Coin Properties — Admin-defined Era and Category option lists for tailoring collection metadata.

v4.0 (Latest)

• Deep Analysis — Optional persisted coin-identification jobs with image analysis, provider routing, replayable SSE progress, cancellation/retry, cited reports, and confirm-gated proposals.
• OCRE Evidence — Roman Imperial coin-type candidates from fixed-template Nomisma SPARQL with canonical links and ODbL 1.0 / American Numismatic Society attribution.
• Nomisma Mint Authorities — Admin-confirmed authority links for global mint locations with CC BY 4.0 attribution.
• RPC Status — Automated RPC integration remains paused because no supported API or downloadable corpus is available; no RPC images or data are ingested.
• Numista Lookup Improvements — Richer editable queries, deterministic relevance scoring, bounded enrichment, caching, telemetry, and selected-reference persistence.
• v3 Foundation — OIDC account linking, security hardening, expanded analytics, and other post-v2 platform work are included in this release.

v2.0

• Quick Capture — Mobile-first draft intake for show-floor photos/notes, resumable drafts, owner-scoped media, and idempotent promotion into normal collection coins.
• Coin Lookup — Photo-based show workflow for NGC Ancients cert extraction, official NGC verification links, Numista fallback matches, and saving lookups to wish list or collection.
• Configurable Coin Properties — Admin-managed Era and Category options used by coin forms and lookup saves.
• CNG Auctions Support — Import CNG lots, sync CNG watched lots, and filter auction tracking by provider alongside NumisBids. CNG can auto-detect hosted auction outcomes where provider data is available; NumisBids remains watchlist/import tracking only and needs manual won/lost and max-bid updates.
• Encrypted Auction Credentials — Stored NumisBids and CNG provider passwords are encrypted at rest with lazy migration for existing plaintext values.
• Coin Sets — Organize coins into themed collections with trend tracking and completion analysis. Standard, goal, smart, and human-reviewed Agentic set types. Snapshot history and value milestones.
• Coin Agent Notes — Save completed Coin Agent answers into Notes through an explicit markdown review dialog.
• Museum Tray Dates — Tray cards show purchase dates in YYYY-MM-DD; wishlist placeholders are more transparent and display TBD.
• Structured Storage Trays — Define backward-compatible Standard Locations or fixed 1–20 by 1–20 Coin Trays in Settings. Assign coins to exact one-based slots and open Collection → Storage Trays for a read-only physical layout. The existing Museum Tray remains the curated, responsive collection view.
• Health Scorecard — Track AI coverage, image coverage, and metadata completeness.
• Enhanced AI agent teams (grading, price trends, gap analysis, photography guide, similar lots).

v1.0

• ✅ Collection CRUD with rich metadata
• ✅ AI-powered coin analysis (Claude/Ollama)
• ✅ AI coin search agent with dealer discovery
• ✅ Wish list with availability checking
• ✅ Auction tracking (NumisBids and CNG Auctions)
• ✅ Sold coin tracking with profit/loss
• ✅ Social features (follow, comment, rate)
• ✅ Collection statistics and portfolios
• ✅ PWA with offline read access
• ✅ External tool server for OpenWebUI integration
• ✅ Multi-auth (JWT, WebAuthn, API keys)
• ✅ Daily featured coins scheduler

Three services, two containers in production:

Browser ──► Vue 3 SPA  ──► Go API (Gin, GORM, SQLite) ──► Python LangGraph Agent
            (PWA)          :8080                          :8081 (stateless, SSE)

The Go API serves both REST (/api/*) and the compiled Vue SPA; it proxies AI requests (including SSE streams) to the Python agent. The Python service is stateless — all configuration (provider, keys, prompts, user context) is passed per-request.

Full details in docs/ARCHITECTURE.md; the binding rationale is captured in ADR 0002 — Three-Service Architecture.

Prerequisites: Go 1.26.6, Node.js 20+, Task (optional), Docker (optional), Ollama (optional — for local AI).

git clone <repo-url> && cd coin-collection-app
task init        # generates .env with a random JWT secret
task up          # API (:8080) + web (:5173)
task up-all      # API + web + Python agent (:8081)

The first registered user becomes the admin and can configure AI providers from the Admin page. For a guided walkthrough see docs/getting-started.md; for production deployment see docs/deployment.md.

task test            # Go architecture + unit tests
task test-agent      # Python agent tests
( cd src/web && npm run type-check )

Run task --list to see all targets.

Design System — Tokens, typography, components documented in Copilot Instructions and locked by ADR 0004.

Product Authority — Per Constitution §0, the hierarchy is: Constitution → PRD → Active Spec → Plan → Tasks → Backlog → Decisions → Agent Judgment.

• Constitution: .specify/memory/constitution.md (v3.1.0) — non-negotiable contract for how this project is built. §0 defines the Hierarchy of Authority.
• Spec workflow: features ship through specs/NNN-*/{spec,plan,tasks}.md per the templates in .specify/templates/.
• Decision records: docs/adr/ (Michael Nygard format, established by ADR 0001).
• Project decisions ledger: .squad/decisions.md; proposals land in .squad/decisions/inbox/.
• AI team (Squad): .squad/team.md and per-agent charters under .squad/agents/.
• Quality Gate & Definition of Done: Constitution §17 and §21 — enforced on every PR.
• Contributing: CONTRIBUTING.md.
• Security: SECURITY.md.

MIT.