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

3.4 KiB

ADDED Requirements

Requirement: REST API endpoints

The system SHALL expose REST API endpoints for all operations currently served by WebForms page methods and Json-*.aspx pages. Endpoints return JSON and follow consistent conventions: resource-oriented URLs, standard HTTP methods, and consistent error response format.

Scenario: List financial accounts

  • WHEN an authenticated client sends GET /api/organizations/{orgId}/accounts
  • THEN the API returns the chart of accounts for that organization as JSON

Scenario: Create expense claim

  • WHEN an authenticated client sends POST /api/organizations/{orgId}/expense-claims with claim data
  • THEN the API creates the claim and returns the new resource with its ID

Scenario: Unauthenticated request

  • WHEN an unauthenticated client calls any API endpoint
  • THEN the API returns 401 Unauthorized

Requirement: WebSocket for real-time updates

The system SHALL provide a WebSocket endpoint for real-time notifications to connected clients. Authentication on WebSocket upgrade uses the same session cookie as REST API requests. Events include: new blockchain deposits detected, task list changes, backend worker status updates.

Scenario: WebSocket connection

  • WHEN an authenticated client connects to the WebSocket endpoint (session cookie sent on upgrade)
  • THEN the client receives real-time events scoped to their active organization

Scenario: Unauthenticated WebSocket rejected

  • WHEN a client without a valid session cookie attempts a WebSocket upgrade
  • THEN the server rejects the upgrade with 401

Scenario: Blockchain deposit notification

  • WHEN the backend worker detects a new deposit to a hot wallet address
  • THEN connected clients for that organization receive a notification via WebSocket

Requirement: Consistent error responses

All API errors SHALL return a JSON body with error (machine-readable code), message (human-readable description), and optional details (field-level validation errors). HTTP status codes follow REST conventions (400 for validation, 401 for auth, 403 for permission, 404 for not found, 500 for server errors).

Scenario: Validation error

  • WHEN a client submits an expense claim missing a required field
  • THEN the API returns 400 with an error body listing the missing fields

Scenario: Permission denied

  • WHEN a user without the CanAttestExpenses permission attempts to attest a claim
  • THEN the API returns 403 with an error body indicating the missing permission

Requirement: Organization-scoped routing

All resource endpoints SHALL be scoped under /api/organizations/{orgId}/ to enforce multi-tenant data isolation at the routing level. The API layer verifies the authenticated user has access to the specified organization before processing.

Scenario: Cross-org access denied

  • WHEN a user belonging only to Organization A requests data for Organization B
  • THEN the API returns 403

Requirement: Static file serving

The API server SHALL serve the React SPA's static assets (HTML, JS, CSS) from a configured directory. All non-API routes SHALL fall through to the SPA's index.html for client-side routing.

Scenario: SPA route fallthrough

  • WHEN a browser navigates to /ledgers/balance-sheet
  • THEN the server serves index.html and the React router handles the route