- 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>
54 lines
2.8 KiB
Markdown
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)
|