FairShare Ledger

Productivity

Original Idea

Rent Split Ledger A mobile app that splits by item, tracks IOUs, and nudges everyone when it's time to settle.

Product Requirements Document: FairShare Ledger

1. Executive Summary

FairShare Ledger is a "Local-First" mobile application designed to eliminate the social friction and mathematical complexity of sharing expenses. Unlike traditional split-check apps, FairShare Ledger focuses on per-item granularity (splitting a single grocery receipt by line item) and automated accountability via smart nudges. Built on a 2026-standard architecture, it offers instantaneous performance, offline capability, and AI-powered receipt processing.

2. Problem Statement

Managing shared household expenses or group travel involves:

  • Complex Math: Manually calculating who owes what for specific items on a 50-item grocery bill.
  • Social Friction: The awkwardness of repeatedly asking friends to "pay me back."
  • Data Silos: Lack of real-time visibility into net balances across multiple groups.
  • Manual Entry: The tedious task of typing in every item from a paper receipt.

3. Goals & Success Metrics

  • Goal 1: Reduce time spent logging an itemized receipt from minutes to under 15 seconds.
  • Goal 2: Increase "settlement speed" (time from expense logged to debt cleared).
  • Goal 3: Provide 100% offline availability for travel scenarios.

Success Metrics:

  • Monthly Active Users (MAU): 50k within first 6 months.
  • Settlement Rate: % of IOUs settled within 7 days.
  • OCR Accuracy: >95% accuracy in item/price extraction.
  • App Responsiveness: <100ms for local UI interactions (Optimistic UI).

4. User Personas

  1. Alex (The Organizer): A tech-savvy roommate who pays the upfront bills and wants an easy way to get reimbursed without being the "bad guy."
  2. Jordan (The Budgeter): Needs to know exactly why they owe $43.52, preferring itemized breakdowns over "equal splits."
  3. Taylor (The Forgetful Friend): Well-meaning but busy; needs gentle, automated reminders to settle up.

5. User Stories

  • As Alex, I want to scan a long grocery receipt so that I don't have to manually type in 30 different items.
  • As Jordan, I want to mark specific items as "mine only" and others as "shared" so that I don't pay for my roommate's expensive steak.
  • As Alex, I want the app to automatically nudge Taylor when a utility bill is 3 days overdue so I don't have to send an awkward text.
  • As Taylor, I want to click a single button to pay my debt via Venmo so I can settle up instantly.

6. Functional Requirements

6.1 Expense Management

  • Itemized Splitting: Users can assign different people or ratios to specific line items.
  • Group Management: Create groups (e.g., "Apartment 4B") with invite codes.
  • Net Balance Engine: Automatically simplifies debts (e.g., if A owes B $10 and B owes C $10, A pays C $10).

6.2 AI & OCR

  • Intelligent Scanning: Use camera to capture receipts; AI extracts merchant, date, tax, and individual line items with prices.
  • Manual Adjustment: Users must be able to "Confirm & Edit" AI-extracted data before saving.

6.3 Settlement & Nudges

  • Automated Nudges: Customizable push notifications via AWS SNS/FCM V1 triggered by EventBridge.
  • Payment Deep-Linking: Direct buttons to Venmo/PayPal pre-filled with the amount and note.
  • Partial Payments: Support for paying off part of a larger debt.

6.4 Offline & Sync

  • Local-First: All data stored in an encrypted local SQLite database.
  • Background Sync: Automatic reconciliation with the server when connectivity returns.

7. Technical Requirements

7.1 Frontend Stack

  • Framework: React Native 0.83 (Mandatory New Architecture/Fabric).
  • State Management: PowerSync (Postgres-to-SQLite sync) + Zustand for UI state.
  • SDK: Expo SDK 55.
  • Routing: Expo Router (for Universal Link support).

7.2 Backend Stack

  • Runtime: Node.js 24.x on AWS Lambda (SnapStart enabled).
  • Framework: NestJS (Lambdalith pattern) with Fastify adapter.
  • Database: PostgreSQL on AWS RDS (using RDS Proxy).
  • Auth: Firebase Auth with custom JWT verification via jose.

7.3 Integrations

  • OCR: Google Cloud Vision API (Raw OCR) + GPT-4o (Structuring JSON).
  • Notifications: AWS SNS + FCM V1 API.
  • Scheduling: AWS EventBridge Scheduler.
  • Payments: Venmo/PayPal Universal Links.

8. Data Model

User

  • userId (UUID), email, displayName, pushToken, venmoHandle.

Group

  • groupId (UUID), name, inviteCode, currency.

Expense

  • expenseId (UUID), groupId, payerId, totalAmount, date, receiptImageUrl.

LineItem

  • itemId (UUID), expenseId, description, price.

Split

  • splitId, itemId, userId, amountOwed, status (PENDING/SETTLED).

9. API Specification (Internal)

| Endpoint | Method | Description | | :--- | :--- | :--- | | /expenses/scan | POST | Upload image -> Returns structured JSON of items. | | /groups/:id/ledger | GET | Returns simplified "Who owes Who" balances. | | /settlements/nudge | POST | Triggers a push notification to a specific debtor. | | /sync | POST | PowerSync stream endpoint for Postgres replication. |

10. UI/UX Requirements

  • Theme: Modern, high-contrast (Dark Mode support).
  • Navigation: Bottom Tab Bar (Home, Groups, Scan, Activity, Profile).
  • Scan Interaction: Floating Action Button (FAB) for "Camera" prominently placed.
  • Feedback: Haptic feedback on successful "Nudge" or "Settle" actions.

11. Non-Functional Requirements

  • Security: PostgreSQL Row-Level Security (RLS) ensuring users only see their own group data.
  • Performance: App launch to interactivity in <1.5s.
  • Encryption: SQLCipher for local storage encryption.
  • Scalability: AWS Lambda scaling to handle up to 5,000 concurrent requests.

12. Out of Scope

  • In-app escrow or direct wallet-to-wallet transfers (we use deep-linking instead).
  • Personal budgeting/spending category analysis.
  • International wire transfers.

13. Risks & Mitigations

  • Risk: OCR fails on crumpled or faded receipts.
    • Mitigation: Provide a fast "Manual Entry" fallback and always allow user editing before final save.
  • Risk: Sync conflicts when two roommates edit an expense offline.
    • Mitigation: Use CRDT-based merging (via RxDB or PowerSync) to prevent data loss.
  • Risk: Payment verification (User marks "Paid" but didn't actually pay).
    • Mitigation: Payee must "Confirm Receipt" of funds before balance is officially zeroed.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize React Native 0.83 project with Expo SDK 55.
  • [ ] Configure mandatory New Architecture (Fabric) in app.json.
  • [ ] Set up NestJS backend with Node.js 24.x and Fastify.
  • [ ] Deploy base infrastructure (RDS Postgres, AWS Lambda, RDS Proxy) using CDK.

Phase 2: Auth & Database Security

  • [ ] Integrate Firebase Auth on Mobile.
  • [ ] Implement custom JWT verification in NestJS using jose.
  • [ ] Configure PostgreSQL Row-Level Security (RLS) policies for tenant_id (groupId).
  • [ ] Setup PowerSync for offline-first replication.

Phase 3: Core Ledger Logic

  • [ ] Implement "Greedy Match-and-Settle" algorithm for debt simplification.
  • [ ] Create UI for Group Management and Expense Itemization.
  • [ ] Build the "Settle Up" flow with Venmo/PayPal deep-link generation.

Phase 4: AI Receipt Scanning

  • [ ] Integrate Google Cloud Vision for DOCUMENT_TEXT_DETECTION.
  • [ ] Implement GPT-4o proxy to transform raw text into LineItem JSON.
  • [ ] Build the "Scan & Verify" UI flow with optimistic loading states.

Phase 5: Nudges & Reminders

  • [ ] Configure AWS EventBridge Scheduler for timezone-aware reminders.
  • [ ] Set up AWS SNS and FCM V1 for push notification delivery.
  • [ ] Implement "Nudge" button with rate-limiting to prevent spam.

Phase 6: Testing & Launch

  • [ ] Performance audit: Ensure SnapStart reduces Lambda cold starts to <500ms.
  • [ ] Security audit: Verify RLS prevents cross-tenant data leaks.
  • [ ] Beta release to 100 users for feedback on OCR accuracy.