Receipt foundation API contracts documentation

epic-receipt-capture-and-attachment-foundation-task-018 — Write developer documentation covering the public contracts of all five foundation components: ReceiptImagePickerIntegration interface, ReceiptImageCompressor API with config options, ReceiptStorageRepository path convention and error types, ClaimReceiptRepository SQLite schema and method signatures, and ReceiptThresholdValidator usage with org config. Include code snippets for the expected wiring via Riverpod and note RLS assumptions for UI epic consumers.

medium priority low complexity documentation pending documentor Tier 5

Acceptance Criteria

Documentation file exists at docs/receipt-foundation-api-contracts.md or equivalent canonical location within the repository

ReceiptImagePickerIntegration interface is documented with all method signatures, parameter types, return types, and thrown exceptions

ReceiptImageCompressor API section lists all config options (maxWidth, maxHeight, quality, format) with type, default value, valid range, and side-effect notes

ReceiptStorageRepository section specifies the full path convention pattern (e.g., receipts/{orgId}/{userId}/{claimId}/{uuid}.jpg) and enumerates all error types with their trigger conditions

ClaimReceiptRepository section includes the full SQLite schema DDL, all public method signatures with parameter/return types, and documents transactional guarantees

ReceiptThresholdValidator section documents the org config shape it reads, the boolean output contract, and example threshold values

At least one complete Riverpod wiring code snippet is included showing provider definitions, dependency injection, and consumer usage for the full chain of foundation components

RLS assumptions section explicitly states which Supabase storage bucket policies are assumed, which tables have row-level security, and what auth context the UI epic must ensure is active

All code snippets compile without errors against the existing codebase (verified by reviewer)

Document reviewed and approved by at least one other developer on the team before marking complete

Technical Requirements

frameworks

Flutter

Riverpod

Dart

apis

Supabase Storage RLS

SQLite (via drift or sqflite)

data models

Receipt

Claim

OrgConfig

ReceiptThreshold

performance requirements

Documentation must be accurate — no stale signatures from refactored code

Code snippets must reflect real provider names used in the codebase

security requirements

RLS assumptions must explicitly document which user roles can read/write receipt storage paths

Document must note that raw image bytes must never be logged or persisted uncompressed outside of ReceiptImageCompressor

Execution Context

Execution Tier

Tier 5

Tier 5 - 253 tasks

Can start after Tier 4 completes

View Full Execution Plan

Implementation Notes

Start by reading the actual source files for all five components to extract current method signatures — do not write from memory. Use Dart doc-comment syntax (///) for inline documentation stubs if none exist, then reference those in the markdown. The Riverpod wiring snippet should show the provider graph in dependency order: ReceiptImagePickerIntegration → ReceiptImageCompressor → ReceiptStorageRepository, with ClaimReceiptRepository and ReceiptThresholdValidator as parallel leaves consumed by the UI layer. Explicitly flag any breaking change risk: e.g., if ReceiptStorageRepository path convention changes, which tables/buckets must also be migrated.

Keep the document in the same git history as the code so drift is visible in PRs.

Testing Requirements

No automated tests required for a documentation task. Manual verification: a developer unfamiliar with the receipt foundation should be able to wire all five components from scratch using only this document without consulting source code. Conduct a brief walkthrough review with one UI epic developer to confirm the Riverpod wiring snippet is accurate and the RLS assumptions are complete.

Component

Claim Receipt Repository

data low

Dependencies (1)

Write an integration test that exercises the full receipt foundation stack: pick raw bytes via mock ReceiptImagePickerIntegration, compress via ReceiptImageCompressor, upload to Supabase Storage via ReceiptStorageRepository, persist the association record via ClaimReceiptRepository, and validate threshold via ReceiptThresholdValidator. Assert that the SQLite record references the correct storage path and that the stored file is accessible via signed URL. epic-receipt-capture-and-attachment-foundation-task-017

Epic Risks (3)

high impact medium prob security

Supabase Storage RLS policies using org/user/claim path scoping may not enforce correctly if claim ownership is not present in the JWT or if path segments are constructed differently at upload vs. read time, leading to data leakage or access denial for legitimate users.

Mitigation & Contingency

Mitigation: Define and test RLS policies in isolation before wiring to app code. Write integration tests that assert cross-org and cross-user access is denied. Use service-role key only in edge functions, never in client code.

Contingency: If client-side RLS proves insufficient, route all storage reads through a Supabase Edge Function that validates ownership before generating signed URLs, adding a controlled server-side enforcement layer.

high impact medium prob technical

Aggressive image compression may reduce receipt legibility below the threshold required for financial auditing, causing claim rejections or compliance failures despite technically successful uploads.

Mitigation & Contingency

Mitigation: Define minimum legibility requirements with HLF finance team before implementation. Set compression targets conservatively (e.g., max 1MB, min 80% JPEG quality) and validate with sample receipt images. Provide compression statistics in verbose/debug mode.

Contingency: If post-compression quality is disputed by auditors, increase the quality floor at the cost of larger file sizes, and add a manual override allowing users to skip compression for PDFs and high-quality scans.

medium impact medium prob dependency

The Flutter image_picker package behaves differently on iOS 17+ (PHPicker) vs older Android (Intent-based), particularly for file types, permission flows, and PDF selection, which may cause platform-specific failures not caught in development.

Mitigation & Contingency

Mitigation: Test image picker integration on physical devices for both platforms early in the sprint. Pin the image_picker package version and review changelogs before updates. Write widget tests using mock file results for each platform branch.

Contingency: If PHPicker or Android Intent differences cause blocking issues, implement separate platform-specific picker delegates behind the unified interface, allowing platform-specific fixes without breaking the shared API.

Quick Links

All Tasks Execution Plan