Proof of Concept

---
ddx:
  id: example.proof-of-concept.depositmatch
  authoring:
    home: repo
  depends_on:
    - example.feasibility-study.depositmatch
    - example.data-design.depositmatch
    - example.security-requirements.depositmatch
  review:
    self_hash: 1a4e090e57a39c4ba3be9461a32b13865453dab1bd9fc9e6049827da15bd90bf
    deps:
      example.data-design.depositmatch: dc25da87b6288f686dfb11eae276dd334aca0dce4d6cd562c8da70b7f169a7c5
      example.feasibility-study.depositmatch: 356da096953895f8c152a1ac8b880fbc03a3617c1c80516e6f0d3b4033a62c72
      example.security-requirements.depositmatch: 2a1f7efe6e55c1edaa67b76e5a11a49be55e4420d9adc456be5482d417312a43
    reviewed_at: "2026-05-15T04:11:24Z"
---

# Proof of Concept: CSV Import and Evidence-Backed Match Review

**PoC ID**: POC-001 | **Lead**: Engineering Lead | **Time Budget**: 5 days | **Status**: Completed

## Objective

**Primary Question**: Can DepositMatch import representative bank and invoice
CSVs, normalize records by firm/client, suggest matches with visible evidence,
and preserve reviewer decisions without implementing bank feeds or ledger
writeback?

**Success Criteria**:

- **Functional**: WORKING: Import two CSV files, normalize records, generate
  match suggestions, require reviewer approval, and record decisions.
- **Performance**: VALIDATED: Process 500 deposits and 500 invoices for one
  client in under 10 seconds on a local development machine.
- **Integration**: VALIDATED: Source files, normalized records, suggestions,
  review decisions, and exports follow the Data Design relationships.
- **Security**: VALIDATED: Firm/client scoping is enforced in API calls and no
  raw financial identifiers appear in telemetry fixtures.

**In Scope**: CSV parsing, column mapping, normalized records, deterministic
matching rules, evidence display payload, reviewer approval/rejection, and
audit-log write.

**Out of Scope**: Production UI polish, bank-feed integrations, accounting
writeback, ML matching, support tooling, and live customer data.

## Approach

**Architecture Pattern**: Thin vertical workflow from CSV upload through
review decision, using the pilot Data Design and Security Requirements.

**Key Technologies**:

- **Primary**: Local API harness, PostgreSQL-compatible schema, deterministic
  matching service, fixture CSVs.
- **Integration**: Object-storage stub for source files and audit-log table for
  reviewer actions.

## Implementation

### Architecture Overview

```text
CSV fixtures
  -> import validator
  -> normalized deposit/invoice records
  -> deterministic matching service
  -> review queue payload with evidence
  -> reviewer decision endpoint
  -> append-only review_decision audit record
```

### Core Components

#### Import Validator

- **Purpose**: Validate required columns, size limits, encoding, and formula
  injection before normalization.
- **Implementation**: Schema-driven parser with per-client column mapping and
  rejected-row report.

#### Matching Service

- **Purpose**: Suggest candidate deposit-to-invoice matches with evidence.
- **Implementation**: Deterministic rules using amount equality, payer
  reference similarity, and date proximity.

#### Review Decision Endpoint

- **Purpose**: Require reviewer approval or rejection before match state
  changes.
- **Implementation**: Transaction writes suggestion status and immutable
  review_decision record with actor, timestamp, action, and source references.

### Integration Points

| Integration | Type | Status | Notes |
|-------------|------|--------|-------|
| CSV fixtures | File input | Working | Covers two representative bank/invoice export shapes |
| PostgreSQL-compatible schema | Database | Working | Uses pilot entities from Data Design |
| Object-storage stub | File/object store | Partial | Stores source-file metadata only |
| Audit log | Database table | Working | Captures reviewer actions and source refs |

## Results

### Test Scenarios

| Scenario | Result | Status |
|----------|--------|--------|
| Import valid bank and invoice CSVs | 500 deposits and 500 invoices normalized with no rejected rows | Pass |
| Import CSV with missing required column | Batch rejected with field-level error report | Pass |
| Import formula-injection value | Value neutralized before export payload generation | Pass |
| Generate suggested matches | 417 exact-amount/date-window suggestions produced with evidence payload | Pass |
| Reviewer approves match | Suggestion marked accepted and review_decision row appended | Pass |
| Cross-firm read attempt | API returns 403 for records outside firm scope | Pass |
| Performance baseline | 1,000 rows processed in 6.8 seconds locally | Pass |

### Findings

- **FINDING 1**: IMPLEMENTATION: CSV-first import is feasible for the pilot if
  per-client column mapping is explicit.
- **Evidence**: Two fixture formats normalized into the same deposit/invoice
  schema and produced a consistent review queue.
- **Implications**: FEAT-001 should include a mapping step and rejected-row
  report, not a fixed one-format parser.

- **FINDING 2**: VALIDATED: Deterministic matching is sufficient for first-pass
  pilot suggestions.
- **Evidence**: Amount/date/payer rules produced reviewable suggestions with
  evidence payloads and no automatic acceptance.
- **Implications**: ML matching is unnecessary for v1 and should remain parked.

- **FINDING 3**: WORKING: Audit-log writes can be transactionally tied to
  reviewer decisions.
- **Evidence**: Approval/rejection tests wrote suggestion state and
  review_decision rows together.
- **Implications**: Review logs can support the PR-FAQ trust model if the
  production design preserves append-only decision history.

### Risks

| Risk | Prob | Impact | Mitigation |
|------|------|--------|------------|
| Fixture CSVs are not representative enough | High | Medium | Run Research Plan sample intake before finalizing parser scope |
| Deterministic matching misses split payments | Medium | Medium | Route ambiguous deposits to exception queue; defer split support if needed |
| Import performance changes with production storage | Medium | Low | Add performance test with production-like storage before pilot launch |

## Analysis

**Overall Assessment**: VIABLE WITH CONDITIONS

**Rationale**: The PoC proves the end-to-end CSV-first workflow can work without
bank feeds or ledger writeback. Production design should proceed, but only
after research collects representative sample files and confirms the required
column mapping scope.

## Recommendations

1. Proceed with FEAT-001 CSV Import and Column Mapping -- the PoC validated the
   core path -- Design now.
2. Keep matching deterministic in v1 -- sufficient for reviewable suggestions
   and easier to explain -- Design now.
3. Add rejected-row reports and formula-injection protection to acceptance
   criteria -- both materially affect safety and supportability -- Before build.
4. Keep ML matching, bank feeds, and ledger writeback out of v1 -- not needed to
   validate the trust model -- Parking Lot.

### Follow-up

- [ ] Update FEAT-001 technical design with mapping and rejected-row behavior.
- [ ] Add CSV import security tests for formula injection and malformed files.
- [ ] Add performance test using production-like object storage and database.
- [ ] Confirm sample-file compatibility through the Research Plan before build.

## Artifacts

Preserved under `proofs-of-concept/POC-001/`:

- **Code**: `import_validator/` (schema-driven parser with per-client column
  mapping and rejected-row report), `matching_service/` (deterministic
  amount, date-window, and payer-reference rules with evidence payload),
  `review_api/` (decision endpoint with the transactional `review_decision`
  write), and `schema.sql` (pilot entities from the Data Design).
- **Data**: `fixtures/acme-bank-2026-05-08.csv` and
  `fixtures/acme-invoices-2026-05-08.csv` (500 deposits, 500 invoices, two
  export shapes), `fixtures/missing-amount-column.csv`, and
  `fixtures/formula-injection.csv`. All fixtures are synthetic; no customer
  data.
- **Evidence**: `evidence/scenario-results.md` (pass/fail per scenario above),
  `evidence/perf-1000-rows.log` (6.8 second local baseline),
  `evidence/cross-firm-403.log` (firm-scope enforcement responses), and
  `evidence/review-queue-payload.png` (suggestion with visible evidence).