- 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>
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:
- CoinGecko (primary) — free tier sufficient for MVP; hourly OHLC endpoint
- CryptoCompare (fallback 1) — activates on CoinGecko timeout or 5xx
- 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)