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
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-claimswith 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
CanAttestExpensespermission 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.htmland the React router handles the route