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

2.2 KiB

ADDED Requirements

Requirement: Document storage and metadata

The system SHALL store uploaded documents (receipts, invoices, supporting files) on the filesystem with metadata in the database. Metadata includes: document type, foreign object reference (expense claim, invoice, transaction), original filename, server filename, file size, uploader, and upload timestamp.

Scenario: Upload document

  • WHEN a user uploads a file attached to an expense claim
  • THEN the file is stored under the configured storage root in a yyyy/mm/dd directory structure and metadata is recorded in the database

Scenario: Retrieve document

  • WHEN a user requests a document by its ID
  • THEN the system serves the file from the storage path recorded in metadata

Requirement: Document type association

Each document SHALL be typed (expense receipt, inbound invoice, outbound invoice, financial transaction support, etc.) and linked to a foreign object by type and ID. A single foreign object can have multiple documents attached.

Scenario: List documents for expense claim

  • WHEN a user views an expense claim
  • THEN all documents of type "expense receipt" linked to that claim are listed

Scenario: Reassign document

  • WHEN an authorized user reassigns a document from one foreign object to another
  • THEN the document's foreign reference is updated

Requirement: Storage path abstraction

The system SHALL access document storage through an IDocumentStorage interface with a default local filesystem implementation. The storage root path SHALL be configurable. This enables a future swap to S3/MinIO (Bucket 2) without changing the application layer.

Scenario: Configurable storage root

  • WHEN the storage root is configured (defaulting to /var/lib/usingcash/upload/ for fresh installs, or pointing at the legacy /var/lib/swarmops/upload/ path for migrations)
  • THEN all document writes and reads use the configured path as the base directory

Scenario: Storage interface isolation

  • WHEN a document is stored or retrieved
  • THEN the operation goes through IDocumentStorage and does not directly reference filesystem APIs in the business logic