SplitBill - Shared Expense Ledger

SplitBill is a mobile app that turns shared expenses usually scattered across chat into a structured group ledger. Users can create a group, invite members with a code, record who paid, and assign each participant’s share through one consistent flow.

1. Product Goal & Core Flow

The product is designed for everyday situations such as trips, shared meals, and household costs. Its MVP focus is keeping the source of every expense clear: who paid, who participated, and what changed.

flowchart LR
    A[Register / Login] --> B[Create or join a group]
    B --> C[Add an expense]
    C --> D[Choose payer and participants]
    D --> E[Select split method]
    E --> F[Save a consistent expense record]

2. Mobile Architecture & Supabase Boundary

The frontend is built with Expo and React Native using TypeScript. TanStack Query manages server state and query invalidation, while Supabase provides the boundary for authentication, PostgreSQL, database functions, authorization, private storage, and the backend’s realtime configuration.

graph TD
    RN[Expo React Native + TypeScript] -->|Supabase JS| AU[Supabase Auth]
    RN -->|Queries & RPC| DB[(PostgreSQL)]
    DB -->|Policies| RL[Row Level Security]
    DB -->|Published tables| RE[Realtime foundation]
    DB -->|Private bucket policies| ST[Receipt storage foundation]

This keeps the UI layer thin: consistency-sensitive operations, such as creating a group and saving an expense with its splits, are centralized in database functions that can be validated within one transaction boundary.

3. Group Management & Invite Workflow

• Owners create a group with a name, description, and default currency.
• The creator automatically becomes an owner member.
• Owners can generate an invite code that remains valid for seven days.
• Other users can preview the code, check its expiry, and join as a member.
• Data access is constrained by group membership rather than by an ID supplied by the client.

Invite lookup and joining are separated into private Supabase helper functions. The Data API exposes only authenticated wrappers, so the invite flow does not need to make the invite table public.

4. Expense Splitting & Transaction Safety

SplitBill supports three ways to divide a cost:

• Equal - divides the amount evenly and handles rounding residue on the final participant.
• Exact amount - lets users enter each participant’s precise share.
• Percentage - lets users enter shares that must total 100%.

The create_expense and update_expense database functions validate the split method, reject duplicate participants and negative amounts, and ensure the split total matches the expense amount. The main record and participant details therefore cannot be saved in a partially successful state.

5. Built Surfaces

The app is divided into surfaces that follow the user’s workflow:

• Authentication, password recovery, and persistent sessions.
• Home ledger and group list.
• Create, edit, and detail views for groups.
• Joining a group through an invite code.
• Member details and owner controls for removing members or deleting a group.
• Create, edit, delete, and detail views for expenses.
• An activity surface prepared for the group’s change history.
• Profile and identity settings.

Shared UI primitives keep the visual language consistent across forms, status marks, paper surfaces, and data lists, making financial context easy to scan on a mobile screen.

6. Security & Android Delivery

All core tables use Row Level Security to constrain reads and writes by role and group membership. Supabase sessions are persisted through AsyncStorage, and authentication callbacks use the splitbill://auth/callback deep link for the mobile flow.

The project is packaged as an Android preview build through Expo Application Services. Its public repository and APK release provide inspectable traces for both the source code and the application artifact.