Files
using.cash/HANDOFF.md
rick 8dea39d16c
CI / build-and-test (push) Failing after 3h11m35s
CI / docker (push) Has been cancelled
Add HANDOFF.md for session continuity
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
2026-04-20 12:39:35 +02:00

6.1 KiB
Raw Permalink Blame History

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

  1. Unit model: cents = satoshis, dollars = microcoins. Both display with 2 decimal places. See accounting-core spec.
  2. VAT: Manual entry for inbound (match receipt exactly). Pre-filled from org default rate for outbound (editable). See accounting-core spec.
  3. Self-attestation: Allowed (sole proprietor use case).
  4. Continuation transactions: Preserved from v5. AddRow on closed-period tx creates/reuses continuation in open period.
  5. Exchange rates: BTC-hub model, micro-BTC scaling (÷1M), BCH exception flagged for investigation.
  6. Documents: Store originals as-is (no rasterization). Legacy PNGs supported. Browser renders PDFs.
  7. 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-goals
  • design.md — 24 architectural decisions (D1–D24), resolved questions
  • specs/ — 17 capability specs (accounting-core is the most important)
  • tasks.md — 137 done, 13 remaining

Files to Read First

  1. openspec/changes/v6-rewrite/design.md — architectural context
  2. frontend/src/components/AccountTreeGrid.tsx — the signature UI component
  3. frontend/src/components/MoneyInput.tsx — just built, the write-path entry point
  4. src/UsingCash.Api/Endpoints/InspectLedgerEndpoints.cs — richest endpoint
  5. src/UsingCash.Logic/Financial/FinancialTransaction.cs — continuation chain logic
  6. AGENTS.md — workflow rules