Files
rick 212f19ac19 Add v6-rewrite OpenSpec: proposal, design, specs, and tasks
Complete specification for rewriting Swarmops v5 as using.cash v6:
- Proposal: scope buckets (Working Rewrite / First Beyond Working / Maybe),
  non-goals (governance, geography, memberships permanently cut)
- Design: 18 architectural decisions including preserved patterns
  (Basic/Logic, stored procs, credential split), new patterns (repository
  classes, chain abstraction, rate providers), and operational concerns
  (Galera awareness, continuation transactions, VAT booking, OOD
  denormalization)
- Specs: 17 capability specifications with SHALL/MUST requirements and
  WHEN/THEN scenarios, covering accounting core, AP/AR, crypto treasury,
  exchange rates, organizations, users/auth, documents, comms, dashboard,
  end-of-month, backend worker, event bus, data migration, API layer,
  frontend app, and CI/packaging
- Tasks: 145 implementation tasks grouped by subsystem, ordered by
  dependency (migration gates API/frontend work)

Two rounds of adversarial review incorporated.

Made-with: Cursor
2026-04-08 16:02:58 +02:00

8.5 KiB

Why

Swarmops v5 is unbuildable. Its build pipeline (CruiseControl.NET, Debian packaging, Mono runtime) has been broken for years, it targets .NET Framework 4.5.2 on Mono, and the ASP.NET WebForms frontend is a dead technology. Meanwhile the software has pivoted from a Pirate Party membership register to a crypto-centric accounting system — but the codebase still carries twenty years of political-organization features (governance, geography hierarchies, membership management) that no longer serve the product's purpose.

The v6 rewrite modernizes the runtime, replaces the frontend, strips the dead weight, and renames the product from "Swarmops" to "using.cash" (namespace UsingCash). The financial core — double-entry ledger, AP/AR, crypto treasury — is preserved and cleaned up. The v5 database is left untouched; v6 gets a clean schema populated by a one-time ETL migration, with closed ledger periods guaranteed to render identically on-screen.

What Changes

Scope Bucket 1 — Working Rewrite

  • BREAKING: Runtime moves from .NET Framework 4.5.2 / Mono to .NET 8+
  • BREAKING: Frontend replaced — ASP.NET WebForms → React + Material UI + TypeScript + Vite
  • BREAKING: Backend HTTP layer replaced — WebForms page methods and Json-*.aspx → ASP.NET Core minimal API + WebSocket
  • BREAKING: Namespace and branding rename — Swarmops.* → UsingCash.*, all PirateWeb/Activizr/Falconwing references removed
  • BREAKING: New database schema — v6 owns its own MySQL database, populated via ETL from v5
  • Accounting core preserved: double-entry ledger, chart of accounts, balance sheet, P&L, budget tracking, continuation transactions for closed-period operations, foreign currency amounts on transaction rows
  • AP/AR preserved: expense claims, inbound/outbound invoices, attestation workflow (self-attestation allowed for sole proprietors), payouts, refunds
  • VAT booking at transaction creation time: inbound VAT on expenses and supplier invoices, outbound VAT on customer invoices — split into dedicated VAT accounts. VAT reporting UI deferred to Bucket 2 but data must be correct from the moment it enters the ledger
  • Crypto treasury preserved: BCH hot wallet with UTXO tracking, abstracted for future chain support
  • Exchange rate system cleaned up: proper JSON parsing of BitPay API, fallback rate sources, BTC-hub model preserved
  • Organizations preserved as multi-tenant boundary (flat, no tree hierarchy)
  • Users replace People/Members — simplified identity with instance-level RBAC
  • Comms/mailing simplified to direct SMTP delivery
  • Documents preserved with local filesystem storage
  • Dashboard tasks preserved
  • Backend worker preserved: exchange rate snapshots, mail processing, heartbeat
  • Event bus preserved (low-priority DB queue, simplified)
  • Dev-mode impersonation ("become admin") preserved
  • Read/Write/Admin DB credential split and stored procedure write pattern preserved
  • Money as Int64 smallest-units preserved; double for intermediate rate calculations (deliberate — decimal causes hard-to-debug issues)
  • Localization: English primary, Swedish secondary, German should-have
  • Sequential journal numbering (OrganizationSequenceId) preserved for legal compliance
  • CI: Gitea Actions + Docker build
  • Migration tool: ETL from v5 MySQL → v6 schema, with multi-level ledger verification (balance sheets, P&L, transaction-level checksums, per-account-per-year totals)
  • ObjectOptionalData EAV migration: financial/org/crypto keys denormalized to first-class columns in v6 schema

Scope Bucket 2 — First Beyond Working

  • Abstract document storage (S3/MinIO)
  • Kubernetes deployment manifests
  • Bank file integration (import/reconciliation)
  • VAT reporting UI and periodic report generation
  • Organization-level RBAC (flat, not tree)
  • Improved continuation transaction UX (future: find a better pattern than silent redirect)

Scope Bucket 3 — Maybe / Later

  • Payroll and salary management
  • Sweden-specific tax tables
  • Additional cryptocurrency chain support
  • Additional localization packs beyond EN/SV/DE

Non-goals

These features are permanently cut from v6:

  • Governance (elections, ballots, motions, internal polls, meetings)
  • Parleys (event attendance tracking)
  • Media tracking (reporters, blog influence)
  • Geography hierarchy (countries, cities, postal codes as organizational structure)
  • Memberships and membership payments
  • Activists and volunteer management
  • PilotInstallationIds (hardcoded beta deployment UUIDs)
  • BitID (dead 2FA technology)
  • PGP key support
  • User-impersonation for help-desk use (admin helping members fill forms)
  • Blog/forum/press watchers and scrapers
  • RSS writer
  • Interface project (functionality absorbed or dropped)
  • FrontSocket / Falconwing (replaced by ASP.NET Core WebSocket)
  • CruiseControl.NET and Debian packaging build infrastructure
  • Boneyard (all legacy site generations)

Capabilities

New Capabilities

  • accounting-core: Double-entry ledger engine — accounts, transactions, transaction rows (including foreign currency amounts), tags, budgets, period closing, continuation transactions, sequential journal numbering, balance/P&L/budget reporting, VAT booking splits
  • accounts-payable-receivable: Expense claims, inbound invoices (supplier), outbound invoices (customer), attestation workflow, receipt validation, payouts, refunds
  • crypto-treasury: BCH hot wallet, UTXO tracking, blockchain transaction ingestion, chain-abstraction layer for future multi-chain support
  • exchange-rates: Rate snapshot system via BitPay API (BTC hub model), proper JSON parsing, fallback sources, fiat-to-fiat derivation
  • organizations: Multi-tenant organization boundaries, org settings, org-scoped data isolation
  • users-and-auth: User identity (replacing People/Members), login, password reset, instance-level RBAC with role-based permissions, dev-mode impersonation
  • documents: File storage and metadata for receipts, invoices, financial supporting docs — local filesystem with path abstraction
  • comms: Simplified outbound email via direct SMTP, mail templates, mail queue processing
  • dashboard: Landing page with task summaries, end-of-month workflow status, quick links
  • dashboard-tasks: Actionable work items (attest expenses, validate receipts, approve invoices) surfaced per-user
  • end-of-month: Monthly workflow — books balancing verification, bank statement upload, close-books checklist, year-end closing journal
  • backend-worker: Background processing daemon — exchange rate snapshots, mail delivery, heartbeat, event bus consumption
  • event-bus: Low-priority asynchronous messaging via database queue between frontend and backend worker
  • data-migration: One-time ETL from v5 Swarmops MySQL to v6 UsingCash schema, with closed-ledger verification (rendered diff)
  • api-layer: ASP.NET Core REST API + WebSocket replacing WebForms page methods and Json-*.aspx endpoints
  • frontend-app: React + MUI + TypeScript SPA — all user-facing pages for Bucket 1 scope
  • ci-and-packaging: Gitea Actions pipelines, Docker image builds, automated testing

Modified Capabilities

(No existing specs to modify — this is a greenfield spec-driven rewrite.)

Impact

  • All code: Every assembly renamed from Swarmops.* to UsingCash.*; all .csproj files rewritten for .NET 8+ SDK-style format
  • Database: New MySQL schema; ~100 stored procedures rewritten (governance/geography/membership procedures dropped); read/write/admin user grants recreated
  • Frontend: Complete replacement — 109 .aspx pages and 27 .ascx controls replaced by React components; jQuery/EasyUI dependencies eliminated
  • Backend: BackendLoop and socket services ported to .NET 8+ hosted services; WebForms-specific code removed
  • Dependencies: Mono runtime dropped; NBitcoin updated; MySql.Data updated; websocket-sharp replaced by ASP.NET Core WebSocket; RestSharp evaluated for replacement; all checked-in DLLs in External Libraries/ replaced by NuGet references
  • Build: CruiseControl.NET config, Debian packaging templates, and all BuildFiles/ infrastructure replaced by Gitea Actions + Docker
  • Configuration: /etc/swarmops/ → /etc/usingcash/; database.config XML format preserved; web.config replaced by appsettings.json
  • File storage: Storage root is configurable; fresh installs default to /var/lib/usingcash/upload/, migrations can point at the legacy /var/lib/swarmops/upload/ path (Bucket 2 adds S3/MinIO abstraction)