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

54 lines
2.8 KiB
Markdown

# 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)