Initial commit

starter-docs/full_overview.md

@@ -0,0 +1,240 @@
+# Cashumints.space API – Full Overview
+
+## Purpose
+The Cashumints.space API is a public, read‑only observability, discovery, and reputation API for the Cashu mint ecosystem.
+
+It exists to:
+- Discover Cashu mints in a decentralized way
+- Track availability, uptime, and incidents over time
+- Fetch and keep mint metadata up to date using NUT‑06
+- Ingest and expose Nostr‑based mint reviews (NIP‑87)
+- Compute transparent and explainable trust scores
+- Provide rich analytics and time‑series data for frontends and wallets
+
+It explicitly does NOT:
+- Custody funds
+- Interact with wallets
+- Simulate balances or volume
+- Require authentication for read access
+
+The API is infrastructure, not a wallet.
+
+---
+
+## Core Design Principles
+
+1. History is never erased
+All raw data is stored and aggregated later. Nothing is overwritten without keeping history.
+
+2. Offline does not mean dead
+Mints move through states: unknown → online → degraded → offline → abandoned. Recovery is always possible.
+
+3. URL is not identity
+Mint identity is stable even if URLs change. One mint can have multiple URLs.
+
+4. Trust is derived, not asserted
+Every trust signal is computed from stored data and exposed with a breakdown.
+
+5. Self‑hostable by default
+SQLite is the default database. PostgreSQL is optional. No Redis or external queues.
+
+---
+
+## High‑Level Architecture
+
+### Layers
+
+1. HTTP API
+- Serves public read‑only endpoints
+- Records pageviews
+- Accepts mint submissions
+- Enqueues background jobs
+
+2. Database
+- SQLite by default
+- PostgreSQL optional
+- Single source of truth for:
+  - mints
+  - mint URLs
+  - probes
+  - metadata snapshots and history
+  - uptime rollups
+  - incidents
+  - reviews
+  - trust scores
+  - pageviews
+  - jobs
+
+3. Workers
+- Stateless background processes
+- Poll database for jobs
+- Perform probes, aggregation, ingestion, scoring
+- Never serve user traffic
+
+---
+
+## Mint Identity Model
+
+### Mint
+A mint is a logical entity identified internally by a stable `mint_id` (UUID).
+
+### Mint URLs
+A mint may expose multiple URLs:
+- clearnet
+- Tor (.onion)
+- mirrors
+
+URLs are aliases, not identities.
+
+Any known URL resolves to the same mint_id.
+
+---
+
+## Mint Lifecycle
+
+### Discovery
+Mints are discovered via:
+- Nostr review events (NIP‑87)
+- User submissions
+- Manual/admin additions
+- Imports
+
+Initial state: `unknown`
+
+### Verification
+After the first successful probe:
+- Status becomes `online`
+- Uptime tracking begins
+- Metadata fetching is enabled
+
+### Failure and Recovery
+- Consecutive probe failures move the mint to `offline`
+- Long‑term offline mints become `abandoned`
+- A successful probe at any time revives the mint
+
+---
+
+## Status Model
+
+Each mint is always in exactly one state:
+
+- unknown: never successfully probed
+- online: recently reachable
+- degraded: reachable but unstable or slow
+- offline: previously online, now unreachable
+- abandoned: offline longer than configured threshold
+
+---
+
+## Probing and Uptime
+
+- Probes are HTTP requests to mint endpoints
+- Every probe stores a result, success or failure
+- Probe frequency adapts to mint status
+- Raw probe data is aggregated into uptime rollups
+
+Rollup windows:
+- 1 hour
+- 24 hours
+- 7 days
+- 30 days
+
+Each rollup stores:
+- uptime percentage
+- average and percentile RTT
+- downtime duration
+- incident count
+
+---
+
+## Metadata (NUT‑06)
+
+- Fetched from `/v1/info`
+- Only fetched after a successful probe
+- Fetched at most once per hour per mint
+- Stored as a current snapshot
+- All changes stored in history
+
+Metadata includes:
+- name
+- pubkey
+- version
+- descriptions
+- contact info
+- MOTD
+- icon_url (stored as URL only)
+- supported NUTs
+- advertised URLs
+- TOS URL
+
+---
+
+## Nostr Reviews (NIP‑87)
+
+- Ingested continuously from configured relays
+- Raw events stored immutably
+- Reviews linked to mints via URLs or identifiers
+- Ratings and content parsed when present
+
+Used for:
+- Display
+- Trust scoring
+- Ecosystem analytics
+
+---
+
+## Trust Score
+
+Each mint has a score from 0–100.
+
+Derived from:
+- Uptime reliability
+- Response speed
+- Review quantity and quality
+- Metadata completeness
+- Penalties for downtime and instability
+
+Scores are:
+- Computed asynchronously
+- Stored with full breakdown
+- Fully explainable
+
+---
+
+## Pageviews and Popularity
+
+- Pageviews tracked per mint page
+- Short‑lived session identifiers
+- No raw IP storage
+
+Aggregated metrics:
+- views_24h / 7d / 30d
+- unique sessions
+- view velocity
+- trending detection
+
+Used as adoption proxies only.
+
+---
+
+## Database Philosophy
+
+- Append raw data
+- Derive aggregates
+- Never delete history
+- Always allow recomputation
+
+---
+
+## Intended Consumers
+
+- Frontends (explorers, dashboards)
+- Wallets (mint selection, warnings)
+- Operators (transparency)
+
+---
+
+## One‑Sentence Summary
+
+Cashumints.space is a decentralized, historical observability and reputation layer for the Cashu mint ecosystem.
+