# using-cash-app — Project Spec ## Repository - Location: `git.falkvinge.net/using-cash/app` - Structure: Polyrepo. Marketing site (`using-cash/website`) stays a static Next.js export with no shared production code. - Package manager: pnpm ## Runtime stack | Layer | Choice | Rationale | |-------|--------|-----------| | Runtime | Node.js 20 LTS | LTS stability; matches k8s base images | | Framework | Next.js 14 App Router | Full-stack TypeScript; server components reduce client bundle; API routes replace separate Express server | | Language | TypeScript strict | No implicit any; required for Drizzle inference | | Auth | Clerk (`@clerk/nextjs`) | Handles sign-up / login / password reset out of the box; saves ~1 week vs custom; no need to self-host vs Supabase Auth | | DB | PostgreSQL 16 | Relational; ACID; strong for time-series FMV lookups | | ORM | Drizzle ORM (`drizzle-orm` + `drizzle-kit`) | Lighter than Prisma; superior TS inference; push-based migrations simplify greenfield dev | ## BCH infrastructure (Q1 — resolved) Self-hosted BCHN + Fulcrum stack (deployed per PRO-167). Not third-party APIs (Bitcoin.com, Blockchair). Data pipeline in Workstream 2 (PRO-183) targets these endpoints directly. ## Price oracle strategy (Q2 — resolved) Three-tier fallback for FMV capture: 1. **CoinGecko** (primary) — free tier sufficient for MVP; hourly OHLC endpoint 2. **CryptoCompare** (fallback 1) — activates on CoinGecko timeout or 5xx 3. **Binance** (fallback 2) — public klines endpoint; no API key required for historical OHLC FMV is captured at **block confirmation timestamp** (not ingest time). This is the IRS "reasonable method" documented position for BCH/USD FMV at receipt date. ## QuickBooks CSV (Q5 — in progress) QBO sandbox account provisioning requested (see PRO-182). Must be validated against a real QBO sandbox by end of Week 2. Blocking Workstream 3 (PRO-184) CSV export validation. ## Auth detail (Q6 — resolved) Clerk. Rationale: fastest MVP DX; no additional infrastructure; `@clerk/nextjs` provides middleware-based route protection, user object in server components, and pre-built sign-in/sign-up UI. Custom auth or Supabase Auth both add ~1 week overhead for the same security outcome. ## Hosting Existing k8s cluster (same deployment pattern as PRO-148). Containerized Next.js app + Postgres. Dockerfile and k8s manifests in `infra/k8s/` within this repo, following PRO-148 conventions. ## DB schema (initial — Workstream 2 will expand) Tables scaffolded in `src/db/schema.ts`: - `users` (Clerk user_id as PK) - `wallets` (xpub, label, user_id FK) - `addresses` (derived addresses per wallet) - `transactions` (txid, wallet_id, amount_bch, amount_usd_fmv, block_time, status, category) - `price_snapshots` (timestamp, bch_usd, source) - `categories` (user_id, name, type: income|expense|internal|uncategorized)