Comprehensive handoff document covering: - What's built and working (backend, frontend, data, infrastructure) - What's next: write path with replayability (new scope), remaining forms, read pages, security, deferred items - Key design decisions to know (unit model, VAT, continuations, etc.) - Dev environment setup commands - OpenSpec artifact locations - Files to read first for context Made-with: Cursor
6.1 KiB
6.1 KiB
Handoff: v6-rewrite
Date: 2026-04-14
Branch: agent/v6-rewrite at commit bb37f83a
Worktree: /home/rick/Lab/Dev/using.cash/.worktree/v6-rewrite
What's Built and Working
Backend (fully operational)
- .NET 8 solution: 8 projects (Common, Basic, Database, Logic, Api, Backend, Migration, Tests)
- MySQL v6 schema: 35 tables, 70 stored procedures, 3 closed-period triggers
- 7 repository classes with read/write/admin credential split (Galera-aware)
- Logic layer: FinancialTransaction (with continuation chains), ExpenseClaim, InboundInvoice, OutboundInvoice, ExchangeRateService (BitPay, micro-BTC scaling), Reports
- 21 API endpoint groups serving real production data
- Background worker: 7 scheduled tasks (exchange rates, mail, heartbeat, etc.)
[LOC]account name resolver (English; multi-language architecture designed)
Frontend (React + MUI + TypeScript + Vite)
- App shell with sidebar nav, org switcher, language selector (EN/SV/DE)
- AccountTreeGrid — signature component with Σ crossfade animation, quarterly columns
- Balance Sheet and P&L — tree grid with quarterly breakdown, CSV download
- Inspect Ledgers — 3 tabs:
- Account Ledger (huvudbok): group view, prior/closing balance, own-only checkbox
- General Journal (grundbok): transaction-grouped, per-row running balance, account type badges
- Search: description, Tx#, amount range, date range
- Transaction detail dialog — clickable from all views, balanced/unbalanced indicator
- Expense Claims — list view + submission form (just built, untested write path)
- MoneyInput — smart decimal comma/point handling with live confirmation
- Dashboard, Chart of Accounts, Crypto Treasury, Login
Data
- Production data migrated from v5 mysqldump (verified: 4,010 tx, 8,590 rows, exact match)
- 3,859 production documents accessible from dev docstore
- v6 database snapshot available for fast restore
- v5 dump archived with sha256 checksum
Infrastructure
- Docker: usingcash-v5 (port 3307), usingcash-v6 (port 3308)
- Gitea Actions CI with Nexus cache mirrors (NuGet + npm)
- Multi-stage Dockerfile
What's Next (Immediate)
1. Write Path with Replayability (NEW SCOPE)
The expense claim form is built but the write path needs design work:
The problem: Submitting an expense claim creates a ledger transaction + document upload. If the user submits, gets a network error, and retries, we could get duplicate entries. For a financial system handling real money, this is unacceptable.
Design questions to resolve:
- Idempotency keys? (client generates a UUID, server rejects duplicates)
- Transaction journaling? (write to a staging table first, then apply)
- Replay log? (record intended operations, replay to different databases)
- How does this interact with the migration tool? (replay writes from dev to production)
Current state: The API endpoint POST /api/organizations/{orgId}/expense-claims creates the claim and ledger transaction in separate calls (not atomic). This needs to be made safe.
2. Remaining Write Forms
- Inbound invoice form (same pattern as expense claim, with supplier details)
- Outbound invoice form (with VAT pre-fill from org default rate, line items)
- These share the MoneyInput, DateInput components and the replayability infrastructure
3. Remaining Read Pages (lower priority)
- Budget vs Actual (10.10)
- End of Month checklist (10.16)
- Organization Settings (10.17)
- User Management (10.18)
- Payout Management (10.14)
4. Security (before production)
- RBAC enforcement middleware (9.19)
- Org-scoping middleware (9.20)
- Year-end closing journal (9.21)
5. Deferred Items
- Document viewer in transaction detail (legacy PNGs + new PDFs)
- Download with business-object naming ("Expense Claim 184.pdf")
- Open Ledgers (domain-based auto-login, per-request locale via Accept-Language)
- Multi-language [LOC] resolution (45 .resx files available)
- WebSocket real-time notifications
- BCH exchange rate exception investigation (see exchange-rates spec ⚠ warning)
Key Design Decisions to Know
- Unit model: cents = satoshis, dollars = microcoins. Both display with 2 decimal places. See accounting-core spec.
- VAT: Manual entry for inbound (match receipt exactly). Pre-filled from org default rate for outbound (editable). See accounting-core spec.
- Self-attestation: Allowed (sole proprietor use case).
- Continuation transactions: Preserved from v5. AddRow on closed-period tx creates/reuses continuation in open period.
- Exchange rates: BTC-hub model, micro-BTC scaling (÷1M), BCH exception flagged for investigation.
- Documents: Store originals as-is (no rasterization). Legacy PNGs supported. Browser renders PDFs.
- Result account balances: From fiscal year start, not all-time. Balance accounts use all-time.
Dev Environment Setup
# Start databases
docker start usingcash-v5 usingcash-v6
# Start backend (port 5222)
cd .worktree/v6-rewrite/src/UsingCash.Api && dotnet run
# Start frontend (port 3000, proxies /api to 5222)
cd .worktree/v6-rewrite/frontend && npx vite --host 0.0.0.0
# Restore v6 database from snapshot (if needed)
docker exec -i usingcash-v6 mysql -uroot -pdev -e "DROP DATABASE usingcash; CREATE DATABASE usingcash;"
docker exec -i usingcash-v6 mysql -uroot -pdev usingcash < /home/rick/Temp/sql/v6-migrated-snapshot.sql
OpenSpec Artifacts
All at openspec/changes/v6-rewrite/:
proposal.md— scope, buckets, non-goalsdesign.md— 24 architectural decisions (D1–D24), resolved questionsspecs/— 17 capability specs (accounting-core is the most important)tasks.md— 137 done, 13 remaining
Files to Read First
openspec/changes/v6-rewrite/design.md— architectural contextfrontend/src/components/AccountTreeGrid.tsx— the signature UI componentfrontend/src/components/MoneyInput.tsx— just built, the write-path entry pointsrc/UsingCash.Api/Endpoints/InspectLedgerEndpoints.cs— richest endpointsrc/UsingCash.Logic/Financial/FinancialTransaction.cs— continuation chain logicAGENTS.md— workflow rules