House Manager is an open source shared expense platform built with TanStack Start, React 19, and Express, designed for bachelor houses, shared flats, and roommates who need to track rent, Wi-Fi, electricity, gas, food, and other shared bills. It replaces the spreadsheet nobody updates and the group chat full of "did you pay this month?" with a single shared source of truth: a member signs in, sees exactly what they owe, submits a payment, and an admin approves it.
The platform is split into two genuinely separate experiences. Members get a calm dashboard showing total due across every month, the current month's breakdown, and a paid-to-date running total that always accounts for partial payments rather than assuming the full bill amount. They can browse a complete bill history grouped by month and filterable by type and status, submit a payment through bKash, cash, bank transfer, or another method with an attached note, and correct and resubmit a rejected payment in a single tap after reading the admin's stated reason.
The admin side gives the house manager full control: custom recurring or one-time bill types beyond the five defaults, one-click monthly bill generation across every active member, ad-hoc charges for damages or late fees targeted at specific members and months, and an approvals queue with a live pending count badge where approving a request settles the underlying bill atomically so nothing is ever double-booked. Member management covers adding, editing, and suspending housemates, with soft-deleted members held in a thirty-day recoverable trash before permanent purge.
Developed by Mhr Rony and released under the MIT license, House Manager keeps a per-member audit trail where every edit, payment, approval, and rejection is logged and viewable as a timeline, so the records stay reliable even when memory does not. Broadcast and targeted announcements surface on member dashboards, and unpaid bills carried over from earlier months are called out separately so nothing quietly slips through the cracks.
Client:
Open Source Project
Industry:
Shared Living & FinTech
Source:
URL:
Challenge
Shared household money is a bookkeeping problem disguised as a social one. The core challenge was building a system that stays accurate across months of partial payments, ad-hoc charges, and members joining or leaving, while remaining simple enough that a housemate with no interest in accounting can open it and immediately understand what they owe.
Two Audiences, One Dataset
Members and admins need completely different views of the same records, and the boundary between them has to be airtight. The solution keeps them as two genuinely separate flows with different auth contexts, different cookies, and different rate limits, so a member session can never accidentally reach an admin endpoint and vice versa. A single shared login with role flags would have been faster to build but far easier to get wrong.
Partial Payments & Carried Balances
A bill is rarely settled in one clean transaction. Someone pays half the rent now and the rest next week, or covers three months at once. Every total on the dashboard therefore had to be derived from the sum of approved payments rather than a boolean paid flag, and unpaid balances from earlier months had to be surfaced separately from the current month so overdue amounts never quietly disappear into a single aggregate figure.
Approvals Without Double-Booking
Payment approval mutates two things at once: the payment request and the bill it settles. Approving the same request twice, or two admins acting concurrently, would corrupt the balance. The approval path had to settle the bill atomically, and rejected payments needed to carry the admin's reason back to the member so the request could be corrected and resubmitted rather than silently abandoned.
Cross-Domain Sessions in Production
Running the API and the frontend on two different registrable domains means browsers treat every request between them as cross-site. Refresh-token cookies had to be configured for that reality, and the API had to trust its reverse proxy correctly, otherwise the login rate limiter would see every request as coming from one address and lock out the entire house after a handful of attempts.
System Design
Frontend Architecture
Built on TanStack Start as the full-stack React framework, with TanStack Router providing type-safe file-based routing where one file maps to one URL, and TanStack Query handling server state and caching so balances stay fresh without manual refetch plumbing. The UI is React 19 and TypeScript throughout, styled with Tailwind CSS 4 and shadcn/ui components built on Radix primitives, with Zod validating every form before submission. Vite and Nitro handle build and output. Member and admin auth contexts are kept as separate providers rather than one shared context.
Backend Architecture
A REST API built with Node.js and Express in TypeScript, organised so controllers stay thin request and response handlers while the real business logic lives in a services layer. Mongoose models define the schemas, Zod validators guard every endpoint's request body, and middleware covers auth, error handling, and rate limiting. Helmet and a CORS allowlist sit in front, and one-off operational scripts handle tasks like creating the first admin and running migrations without needing the UI.
Authentication & Sessions
Short-lived JWT access tokens are paired with refresh tokens stored in httpOnly cookies that rotate on every use, so a replayed old token revokes the whole session rather than granting access. Access and refresh secrets are required to be distinct. Member and admin sessions use separate cookies, separate paths, and separate auth contexts. Passwords are hashed with bcrypt at a configurable cost factor and are never stored or logged in plaintext. Auth routes carry their own tighter rate limit on top of the general limiter.
Billing Data Model
Bill types are data rather than hardcoded enums, so rent, Wi-Fi, electricity, gas, and food ship as defaults while the admin can add further recurring or one-time types such as a yearly maintenance charge. Bills are scoped to a member and a target month, payments reference the bill they settle along with a method and an optional note, and approval state is explicit so pending, approved, and rejected requests are all first-class. Every mutation against a member's bills is written to an audit log that can be replayed as a timeline.
Member Lifecycle & Recovery
Housemates can be added, edited, suspended, or soft-deleted. Soft deletion moves a member into a thirty-day recoverable trash rather than removing the record, which preserves the billing history tied to them and leaves room to undo a mistake before a permanent purge. Only one admin account can ever exist: a first-run setup route creates it, then refuses to create another.
Deployment Topology
The API runs on Render and the frontend on Vercel, with the backend deployed first because the frontend needs its URL and the backend needs the frontend's origin for its CORS allowlist. Proxy trust is enabled so per-IP rate limiting sees real client addresses instead of the load balancer, and the refresh cookie's SameSite policy is set for cross-site delivery because the two hosts are different registrable domains. A cold-start notice component covers the wait when a free-tier API instance spins back up.
Results
House Manager is live and open source under the MIT license, replacing the spreadsheet-and-group-chat workflow with one shared record that both sides of the house can trust. Members stop guessing what they owe and admins stop chasing people for money.
Member Dashboard
A live dashboard showing total due across every month, the current month's breakdown by bill type, and a paid-to-date running total that accounts for partial payments rather than assuming full bill amounts. Unpaid bills from earlier months are called out separately as overdue so they never blend into the current balance. House announcements from the admin, whether broadcast or targeted at one member, appear directly on the dashboard.
Bill History & Payment Submission
Every bill ever issued, grouped by month and filterable by type and status, with a lifetime billed-versus-paid summary. Payments are submitted by choosing a method — bKash, cash, bank transfer, or other — and attaching a note, then sent for admin approval so no cash changes hands unrecorded. A rejected payment displays the admin's reason and can be corrected and resubmitted in one tap instead of starting over.
Admin Billing Controls
Custom bill types extend the five defaults with any recurring or one-time charge the house needs. Monthly generation takes an amount per bill type and issues bills for every active member in one click. Ad-hoc dues charge one or more members for a damage, late fee, or anything custom, with a reason and a target month attached. House-wide totals for the current month sit alongside a rolled-up view of unpaid balances carried over from previous months.
Approvals Queue & Audit Trail
Submitted payments land in an approvals queue with a live pending-count badge in the navigation, and approving a request settles the underlying bill atomically with no risk of double-booking. Rejections carry a written reason back to the member. Every action taken against a member's bills — edits, payments, approvals, rejections — is logged and viewable as a per-member timeline, which makes disputes a matter of reading the record rather than comparing memories.
Member Management
Add, edit, suspend, or soft-delete housemates from the admin panel, with deleted members held in a thirty-day recoverable trash before permanent purge so an accidental removal does not take its billing history with it. A first-run setup flow creates the single admin account for the house and then refuses to create another, and housemates sign in at the app root.
Security Posture
bcrypt password hashing with no plaintext storage or logging, short-lived access tokens with rotating httpOnly refresh cookies where a replayed token revokes the session, separate cookies and auth contexts for member and admin flows, rate limiting on every route with a tighter fixed limit on auth endpoints, plus Helmet, CORS allowlisting, and Zod validation on every request body.
Open Source
Released under the MIT license and published on GitHub with full setup documentation: local development for both the API and the frontend, a documented environment variable reference for each side, available scripts, and a step-by-step production deployment guide covering the Render and Vercel pairing including the proxy and cookie settings that cross-domain sessions depend on. Anyone can run it for their own house, fork it, or ship it as their own thing.
