Build an operational layer over the external financial source, not a replacement

Context#

GoldCash, a family credit operation, runs its financial records in Fomentis, an external system that is the operation's authority for financial facts. The operation needed a reliable view of its portfolio and of what required collection work. The data was available as periodic spreadsheet exports.

What was known when the decision was made (product specification v0.1, 2026-08-17): the operational system owns operational facts; Receiva would import and validate exports and add separate managerial interpretation. The named Fomentis/GoldCash source contract was formalized later.

Problem#

How should Receiva relate to the system that already holds the financial truth?

Constraints#

• The financial system stays in use and remains authoritative.
• Receiva's implemented path to the data used periodic file exports.
• Sources differ in kind, including evidence reconstructed by hand.
• One engineer, inside a small operation that could not stop to migrate.
• Source files contain personal data of the operation's customers.

Evidence#

Technical references below come from Receiva's private repository. They are kept as provenance for audit, not as public links.

• docs/product/product-spec-v0.1.md §45–50 (source ownership), §70, §86 (periodic XLSX/CSV exports), §242–251 (out of scope: collections CRM, replacement of the source system, write-back).
• docs/product/mvp-scope-v0.1.md §11–13: the operational system remains the source of truth; Receiva is a downstream layer.
• docs/product/financial-safety-gate-v2.1.md §5: Fomentis remains the authoritative financial source; Receiva does not synchronize with it.
• Migration 20260818230000_financial_safety_gate_v21: database trigger that prevents updates and deletes on accepted source tables.
• src/lib/import/source-contract.ts: source contract FOMENTIS / GOLDCASH.

Validation scope: the decision is confirmed by the implementation evidence above. Daily use in the operation is the author's own account, not a measured record.

Alternatives considered#

The specification records the rejected options as explicit exclusions, not as a scored comparison. The assessment below is written now and labeled as such.

1. Replace the financial system. Would give full control of the model. Excluded: migration risk to an operation that has to keep running, and it would move financial authority into a new, unproven system.
2. Synchronize and write back. Would keep both systems aligned automatically. Excluded: Receiva would be able to change financial truth, and it would require an integration Receiva did not have.
3. Build a collections CRM as the primary system. Would cover follow-up quickly. Excluded: it would create a second, competing record of the portfolio.
4. Downstream layer over immutable imports. Selected.

Decision#

Receiva is a downstream operational layer. It imports complete exports, stores them as immutable observations, reconciles them, publishes coherent positions, and keeps its own operational state separately. It never writes to the financial system.

Consequences#

Positive:

• Financial truth has one owner; Receiva cannot corrupt it.
• Every figure can be traced back to a file, period and row.
• The operation adopted it without replacing or migrating away from the financial source system.
• Operational features (collection entities, reopening rules) were added without touching source data.

Negative:

• Freshness depends on export cadence, and imports are a manual step.
• Actions taken in Receiva do not flow back to the financial system.
• Some routines stay manual (daily closing).
• Identity of source records must be maintained through durable source identities rather than foreign keys.

Trade-offs#

Accepted: manual imports, no write-back and a duplicated storage of source positions, in exchange for integrity, without replacing or migrating away from the financial source system. Postponed: API integration (the specific reason for not pursuing it was not recorded beyond scope deferral). Not addressed by this decision: individual user identity, which remains a separate open gap.

Later evidence (after the decision)#

• 2026-08-18: source-mutation trigger added.
• 2026-08-28: collection entities and automatic reopening implemented on top of the separated state (commit 3e5a4d6).
• Published-position reads: OperationalState.currentPublishedPositionId.

Applicability (interpretation)#

When a business depends on a system it will not replace, the first question is whether the problem is the system or the lack of a trustworthy view of it. A read-only layer with preserved origin can solve the second without the cost and risk of the first.