A private shared-expense and settlement platform for flatmates, roommates, and small groups.
A shared expense management platform that helps flatmates and small groups track expenses, split costs fairly, and settle balances through a transparent, ledger-based financial model.
Instead of manually calculating who owes whom, FlatLedger maintains individual obligations between users and derives balances directly from them — so nothing gets lost as the transaction history grows.
🔗 Live Application: https://flatledger-keshav.web.app/
FlatLedger is a shared expense management application designed for flatmates, roommates, and small groups.
It provides a structured way to record shared expenses, calculate individual shares, track outstanding obligations, record payments, and maintain a transparent financial history between group members.
The application supports:
- Villa / group based expense management
- Shared expense splitting
- Equal and exact amount splits
- Individual balance tracking
- Payment recording
- Obligation tracking
- Automatic balance calculation
- Payment and expense history
- Member management
- Invitation-based group joining
- Dark and light themes
- Real-time Firebase-backed data
- Cached application state with explicit refresh/invalidation
Managing expenses between flatmates often becomes difficult when there are many transactions.
For example:
- One person pays for groceries
- Another pays for electricity
- Someone pays for a cab
- Multiple people participate in each expense
- Partial payments happen later
- Old obligations may already have been settled
Manually calculating the final balance becomes increasingly error-prone as the number of transactions grows.
FlatLedger solves this by maintaining individual obligations between users and deriving balances from those obligations.
The goal is to make group finances:
Simple • Transparent • Trackable
The home dashboard gives members a quick view of their Villa, group balance, and members at a glance.
Each member can drill into their one-on-one balance with another user, view the running activity feed, and switch between dark and light themes.
- Create shared expenses
- Expense title and description
- Expense categories
- Select participating members
- Record who actually paid
- Support equal splitting
- Support exact-amount splitting
For equal expenses:
Total Expense
↓
Participants
↓
Equal Individual Shares
For exact expenses:
Total Expense
↓
Custom Amount Per Member
↓
Validated Total
Exact split amounts are validated against the original expense total before the expense is created.
Every expense creates financial obligations only for participants who owe the person who paid.
Example:
Rahul pays ₹1000
Rahul's share ₹250
Keshav's share ₹250
Aman's share ₹250
Rohan's share ₹250
Keshav → Rahul ₹250
Aman → Rahul ₹250
Rohan → Rahul ₹250
This creates a structured ledger instead of directly modifying a user's final balance.
FlatLedger also handles opposing obligations between two users.
Example:
Keshav → Rahul ₹500
Rahul → Keshav ₹200
The ledger can offset the opposing obligations so that the remaining relationship becomes:
Keshav → Rahul ₹300
This prevents unnecessary back-and-forth settlement between users.
Users can record payments against their outstanding obligations.
Supported behavior includes:
- Partial payments
- Full payments
- Remaining balance calculation
- Payment history
- Automatic obligation updates
- Updated personal balances
Payments are treated as actual money movements, rather than blindly reversing or rewriting an entire expense.
Each member can view their financial relationship with another member.
The personal ledger displays:
- Net balance
- Amount they owe you
- Amount you owe
- Total paid by each person
- Individual shares
- Related transactions
- Outstanding payment amount
Example:
NET BALANCE
-₹248
They owe you ₹0
You owe ₹248
Pay ₹248
FlatLedger organizes expenses inside shared groups called Villas.
Each Villa provides:
- Members
- Shared expenses
- Group balance
- Activity history
- Invitations
- Villa settings
Users can create or join multiple Villas.
- View Villa members
- Owner/member roles
- Invite members
- Join requests
- Member-specific balances
- Individual transaction history
FlatLedger maintains a chronological activity feed for important financial actions.
Tracked activities include:
- Expense creation
- Payments
- Other ledger events
The history provides a transparent record of what happened inside the Villa.
The application supports both:
- 🌙 Dark Mode
- ☀️ Light Mode
The same application workflow is available in both themes.
FlatLedger follows a layered Flutter architecture.
┌─────────────────────────┐
│ UI Layer │
│ Screens / Widgets │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ Riverpod Providers │
│ State / Cache / Refresh│
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ Action Controllers │
│ Expense / Payment etc. │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ Repository Layer │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ Service Layer │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ Cloud Firestore │
└─────────────────────────┘
The architecture separates UI, state management, business actions, repositories, services, and Firebase persistence. The project also uses provider invalidation to refresh affected cached data after financial writes.
The core financial workflow is:
Create Expense
↓
Calculate Individual Shares
↓
Create Expense
↓
Create Expense Splits
↓
Create Obligations
↓
Check Opposing Obligations
↓
Apply Offset
↓
Updated Balance
When a payment occurs:
Payment
↓
Allocate Payment
↓
Update Obligations
↓
Create Payment Activity
↓
Refresh Balance
↓
Updated Personal Ledger
This keeps expenses, obligations, and payments as separate financial concepts.
FlatLedger uses Riverpod to manage cached application state.
Financial writes trigger refreshes for affected data such as:
- Villa balance
- Expense history
- Activity history
- Personal ledgers
This allows the UI to reflect newly-created expenses and payments without requiring the user to restart the application.
The architecture specifically uses family-scoped data where appropriate and explicit invalidation after write operations.
FlatLedger uses Firebase as its backend infrastructure.
- Firebase Authentication
- Cloud Firestore
Firestore acts as the persistent source of truth for:
Users
↓
Villa Memberships
↓
Expenses
↓
Expense Splits
↓
Obligations
↓
Payments
↓
Activities
The financial model is centered around separate entities:
Villa
│
├── Members
│
├── Expenses
│ │
│ └── Expense Splits
│
├── Obligations
│
├── Payments
│
└── Activities
An expense represents the original transaction.
An expense split represents each participant's share.
An obligation represents money one user owes another.
A payment represents an actual settlement between users.
This separation allows FlatLedger to handle partial settlements and changes without treating an expense itself as a payment.
| Layer | Technology |
|---|---|
| Framework | Flutter |
| Language | Dart |
| State Management | Riverpod |
| Authentication | Firebase Authentication |
| Database | Cloud Firestore |
| Navigation | GoRouter |
| Architecture | Repository + Service Layer |
| Platform | Android / Web |
| UI | Material-based responsive interface |
FlatLedger is also available as a mobile application.
App Download: Coming Soon
This repository contains a showcase version of the FlatLedger source code.
flatledger/
│
├── assets/
│ └── branding/
│
├── docs/
│
├── lib/
│ ├── core/
│ ├── features/
│ ├── models/
│ ├── providers/
│ ├── repositories/
│ ├── services/
│ └── ...
│
├── screenshots/
│ ├── home.webp
│ ├── dashboard-dark.webp
│ ├── people.webp
│ ├── person-balance.webp
│ ├── activity.webp
│ └── dashboard-light.webp
│
├── pubspec.yaml
├── analysis_options.yaml
└── README.md
This public repository intentionally does not contain production Firebase configuration or platform-specific deployment files.
Excluded from the public showcase include:
- Firebase project configuration
- Firebase application configuration
- Android project files
- iOS project files
- Web deployment configuration
- Windows / macOS / Linux platform files
- Environment files
- API credentials
- Service account credentials
- Signing keys
- Generated build files
The public repository is therefore intended primarily for:
- Architecture review
- Portfolio presentation
- Code reference
- Project documentation
The public repository is provided as a portfolio and architecture showcase. Firebase configuration, production environment configuration, and platform-specific application files are intentionally excluded.
FlatLedger was built around a simple objective:
Make shared finances easier to understand and settle.
The project focuses on maintaining a clear separation between:
Expense
≠
Share
≠
Obligation
≠
Payment
This allows the ledger to represent real financial relationships rather than simply storing a final balance.
Potential future improvements include:
- Advanced settlement optimization
- More flexible split types
- Improved notification system
- Expanded analytics
- Recurring expenses
- Better offline support
- More advanced expense filtering
- Additional payment integrations
Keshav B.Tech CSE Bennett University
If you find FlatLedger interesting, consider giving the repository a star ⭐ on GitHub.