Files
henrik.larssonandPaperclip a5a680ad46 feat: scaffold using-cash-app with OpenSpec workflow
- Next.js 14 App Router + TypeScript strict + pnpm + Tailwind
- Clerk auth middleware (routes /dashboard protected, /sign-in exposed)
- Drizzle ORM + Postgres schema: users, wallets, addresses,
  transactions, price_snapshots, categories with proper enums + FKs
- OpenSpec 1.4.1 initialized with Claude Code skills/commands
- openspec/project.md: CTO architecture decisions (BCH Q1, oracle Q2,
  auth Q6, DB/ORM, polyrepo, k8s hosting)
- openspec/config.yaml: spec-driven schema + project context
- openspec/changes/scaffold-app: first change with specs (5 ADDED
  requirements, validate --all passes)
- Multi-stage Dockerfile (deps → builder → runner, node:20-alpine)
- k8s manifests: namespace, deployment, service, ingress (infra/k8s/)

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-27 09:35:26 +00:00

2.8 KiB

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)