FairShare

Inspiration

We built FairShare because we have lived this problem. The most exhausting part of shared living was never the money—it was the mental load of being the one who noticed the toilet paper was running low, remembered the electricity bill was due, and chased the others to pay their share. We watched the person doing the invisible labor slowly become the "nag," while the resentment grew in silence. We wanted to build the system we wished we'd had: one that removes the burden of manual tracking and replaces it with automated, guilt-free settlement.

This is not a niche frustration. Shared living is a long-term economic reality for millions. Research from Nationwide Building Society shows that the average age of someone in a UK house share has risen to 35, with 69% of people saying they simply cannot afford to live alone. The same study found that 46% of people in shared living say it has negatively affected their relationships and personal lives.

The conflict is rarely about the rent itself—it is about the invisible labor that surrounds it. A poll of 2,000 UK adults found that disagreements about money and bills (32%) top the list of the most serious issues in house shares, followed by hygiene (25%) and cleaning (20%). Nearly a third of people (31%) say they regularly have to chase housemates about finances. Research from Smart Energy GB found that 78% of house-sharers believe having a way to track energy usage would have reduced the number of arguments over bills. The financial cost of this inequity is real, too: Barclays research found that renters lose an average of £553 per year because housemates fail to pay their share.

This problem is magnified by the "mental load"—the cognitive work of noticing, planning, and delegating household tasks. SpareRoom data shows that 43% of UK flatmates say the wage gap has sparked rows, with energy and heating usage (77%) and contributions to communal supplies like toilet roll (48%) as the top triggers. Existing solutions like Splitwise have validated the market (raising over $31.9 million and serving millions of users), but they are fundamentally flawed: they are manual record-keeping systems that require the person already doing the invisible labor to also do the administrative work of nagging. As one frustrated user put it, these apps "almost work"—but the friction of manual entry means the burden stays hidden, and the resentment stays.

We built FairShare because we believe the person who remembers to buy the toilet paper should not also have to send the payment reminder. By ingesting hard data (AI bills, IoT smart plugs, one-tap mental load logs) and executing real-time settlements via PayPal, we move the household from a system of manual nagging to automated financial equilibrium. We are not just splitting bills; we are settling the invisible debts that tear shared homes apart.

What it does

FairShare is a continuous, usage-aware settlement engine that functions as an operating system for household economic equilibrium. It is designed to solve the root cause of roommate conflict: the invisible labor and mental load that traditional expense-splitting apps completely ignore.

Here is exactly how the platform works, from data ingestion to financial execution:

1. Zero-Friction Data Ingestion (Solving the "Manual Entry" Problem) Traditional apps fail because they require users to manually type in every expense. If logging takes more than five seconds, exhausted roommates simply won't do it. FairShare attacks this friction from three angles:

AI Bill Ingestion: Users can upload a photo or PDF of a utility bill. Our AI pipeline (powered by Google Gemini with an OpenRouter failover) extracts the total cost, categorizes the expense (e.g., Electricity, Water), and automatically calculates the fair share for each roommate.

Continuous IoT Feeds: We built a hardware adapter interface to ingest real-time data. In the demo, users can simulate a smart plug feed (e.g., 5kWh of electricity). The system instantly attributes this usage to the specific roommate who consumed it, proving that FairShare is a continuous monitoring system, not just a once-a-month ledger.

1-Tap Invisible Labor Logging: Money isn't the only cost. If a roommate spends two hours deep-cleaning the kitchen or buys communal toilet paper, they can tap a single button to log it. This assigns a tangible credit to the "mental load" and physical effort that usually goes uncompensated.

1. The Fairness Ledger (Transparency over Precision) All of this data flows into the centerpiece of the app: an AG Grid-powered data table called the Fairness Ledger. We believe in showing the math, not hiding it. The ledger explicitly displays the Total Cost, the Split Rule (e.g., Equal 3-way, Usage Weighted), the Fair Share, what was Actually Paid, and the resulting Balance. Red rows mean a roommate over-benefited and owes money; green rows mean they over-contributed and are owed money. By making every calculation transparent, we remove the "shame" and guesswork from shared expenses.

2. The PayPal Settlement Fabric (Executed Transactions, Not Advice) Insight without action is useless. The core differentiator of FairShare is that it doesn't just tell you who owes what—it executes the financial settlement instantly through the PayPal REST API:

Invoicing (Collecting): When a roommate over-benefits (shows a red balance), the app uses the PayPal Invoicing API to generate a real, payable invoice. The user doesn't have to nag or send a Venmo request; the system does it automatically.

Payouts (Reimbursing): When a roommate over-contributes (shows a green balance, like the person who bought the groceries), the app uses the PayPal Payouts API to reimburse them directly to their PayPal account.

The Result: FairShare transforms the household from a system of manual nagging into automated financial equilibrium. The roommate who remembers to buy the toilet paper is no longer burdened with chasing down the money. The app tracks the invisible labor, shows the math transparently, and uses PayPal to settle the debt before the resentment even has a chance to build.

How we built it

We architected FairShare to be resilient, transparent, and production-ready, with every decision driven by the need to minimize user friction while guaranteeing a flawless demo experience.

Frontend & Architecture (Next.js & TypeScript) We chose Next.js 14 (App Router) with TypeScript and Tailwind CSS for a strictly typed, server-side rendered architecture. The frontend is split into a marketing landing page (to frame the problem) and a protected dashboard (the application OS). TypeScript was non-negotiable: in a financial application handling real currency and API payloads, type safety prevents silent failures.

The Fairness Ledger (AG Grid) The centerpiece of the dashboard is an AG Grid Community table. We chose AG Grid over a standard HTML table because it provides enterprise-grade features out of the box: sorting, filtering, and custom cell rendering. We used dynamic cellStyle rules to color-code balances (red for debt, green for credit) so users can instantly see the inequity. This fulfills our core design principle: transparency over precision. Every calculation is visible, sortable, and auditable.

The AI Pipeline (Gemini + OpenRouter) We needed multimodal AI to parse bills and receipts, but we knew that free-tier AI APIs are notoriously unreliable. We built a two-tier failover system:

Primary: We call Google Gemini 3.8 Flash directly via the @google/genai SDK to leverage our free-tier quota.

Fallback: We implemented a strict 8-second Promise.race timeout. If Gemini is experiencing a 503 high-demand spike, the request is killed, and we instantly pivot to OpenRouter, using the OpenAI SDK format to call a vision-capable model. This ensures the user never waits 5 minutes for a response; the system either succeeds instantly or fails over gracefully.

The PayPal Settlement Fabric (Invoicing & Payouts) We integrated both sides of the PayPal REST API.

For Invoicing, we use the v2 API to generate real invoices for users with positive (red) balances.

For Payouts, we use the v1 API to issue real reimbursements to users with negative (green) balances. We handled the OAuth2 token generation manually to ensure we had full control over the authentication lifecycle, ensuring the settlement is a real financial action, not a mockup.

Resilience & Deployment We deployed the application on Render, using environment variables to securely manage API keys. To combat Render's free-tier sleep behavior (which would ruin a live demo), we created a lightweight api/health endpoint and set up a cron job to ping it every 5 minutes, ensuring the instance is always warm and ready for the judges.

Challenges we ran into

Building FairShare was a masterclass in navigating the unpredictable realities of external APIs and free-tier infrastructure. We hit three major walls, and solving them shaped the final architecture of the application.

1. The "Invisible" API Timeout (Gemini & OpenRouter) Our biggest technical hurdle was AI reliability. We wanted to use Google Gemini 3.8 Flash for multimodal bill extraction, but on the free tier, the model frequently returned 503 Service Unavailable errors due to high demand. Worse, when it did respond, it sometimes took over 5 minutes to process a simple 58kb JPEG. For a demo video that must be under 3 minutes, a 5-minute wait was a death sentence.

We solved this by ripping out our initial retry loop and replacing it with a strict 8-second timeout using Promise.race. If Gemini doesn't respond in 8 seconds, the request is instantly killed, and the system pivots to OpenRouter. We then hit a second wall: OpenRouter's default token reservation was too high for our account, causing a 402 Payment Required error. We fixed this by explicitly capping max_tokens to 500. Finally, we had to handle the fact that DeepSeek (on OpenRouter) initially rejected image inputs because we were using a text-only model slug. We resolved this by routing OpenRouter to a vision-capable Gemini model, giving us two independent, reliable pipelines.

1. The Sandbox PayPal Payout Restriction We successfully implemented PayPal Invoicing early on, but Payouts (reimbursing users) proved much harder. PayPal's Payouts API requires the business account to have a verified identity, linked bank account, and sufficient balance. In the sandbox environment, these requirements are strict and often block the API. We had to build a robust error handler that catches the INSUFFICIENT_FUNDS and PERMISSION_DENIED errors and surfaces them gracefully in the UI. We also learned to prioritize Invoicing as the primary settlement path (since it has almost no sandbox friction) while building the Payouts integration to be fully functional once the sandbox permissions are granted.

2. The TypeScript Production Build Trap Our app ran perfectly in local development, but the Render production build failed immediately. Next.js's development mode is forgiving, but npm run build enforces strict TypeScript checking. The openai SDK does not officially type the models array (OpenRouter's fallback feature) and AG Grid's cellStyle function strictly required a fontWeight property, not undefined. We had to dive into the TypeScript error logs, add a @ts-ignore for OpenRouter's proprietary payload, and strictly type the AG Grid CellStyle return object. This taught us that "it works on my machine" is never enough.

3. The Render Sleep Problem After deploying to Render, we realized that the free tier spins down after 15 minutes of inactivity. This means a judge clicking our link would stare at a blank screen for 50 seconds while the app booted up. We solved this by building a lightweight /api/health endpoint and setting up an external cron job to ping it every 5 minutes. This keeps the instance warm and guarantees the app is always responsive for the judges.

Accomplishments that we're proud of

We are very proud of what we built in just five days, but three specific accomplishments stand out:

1. We built both sides of the PayPal settlement fabric Many hackathon projects integrate PayPal to accept a one-time payment and call it a day. We went much further. FairShare implements the full lifecycle of household settlement:

PayPal Invoicing (Collections): When a roommate over-benefits, the system generates a real, payable invoice via the v2 API.

PayPal Payouts (Reimbursements): When a roommate over-contributes, the system executes a real payout via the v1 API. We handled the OAuth2 token generation, currency handling (GBP), and error management for both APIs. The app doesn't just give financial advice—it executes the financial action.

1. We built a bulletproof AI pipeline that survives API outages The most impressive engineering feat is invisible to the user. We knew that free-tier AI APIs are unreliable, so we built a two-tier failover system. If Google Gemini fails or times out after 8 seconds, the system instantly pivots to OpenRouter. We also added robust JSON parsing (using a custom safeJsonParse function) that strips markdown formatting if the AI hallucinates it. This means the demo never breaks, even if Google's servers go down. The judges will see a seamless experience, but under the hood, it's a resilient, production-grade pipeline.

2. We made invisible labor quantifiable and transparent The core thesis of FairShare is that fairness is about more than just money. We are proud that we successfully translated "invisible labor" into a tangible, auditable data structure. The AG Grid ledger explicitly shows the Split Rule, the Fair Share, what was Actually Paid, and the resulting Balance. The 1-tap buttons for "Mental Load" and "Groceries" prove that we designed for the 5-second rule: if logging takes too long, it won't happen. We built a system that actually removes friction from the user's life.

What we learned

Building FairShare in five days was an intense masterclass in production engineering. We walked away with three hard-earned lessons that changed the way we think about building software:

1. Resilience is more important than perfection When we started, we assumed that if we just wrote the right code, the AI would work. We quickly learned that external APIs—especially free-tier ones—are inherently unreliable. Google Gemini would return 503 errors, OpenRouter would reject requests due to token limits, and PayPal's Payouts API would throw permission errors. We learned that the mark of a mature application is not whether it avoids failures, but how gracefully it handles them. Implementing Promise.race timeouts, fallback pipelines, and safeJsonParse functions taught us that defensive engineering is not a nice-to-have—it is the foundation of a demo that doesn't break on stage.

2. The gap between "local dev" and "production build" is brutal Our app ran flawlessly on localhost:3000. The moment we pushed it to Render, it failed the build. We learned the hard way that Next.js's development mode is forgiving, but npm run build enforces strict TypeScript rules. The openai SDK doesn't officially support OpenRouter's models array, and AG Grid's cellStyle function rejected our loosely typed return object. We had to dive into error logs, add @ts-ignore annotations, and strictly type our returns. This taught us that "it works on my machine" is never enough—you must test against the same environment the judges will use.

3. Small design decisions have outsized impact The decision to add a strict 8-second timeout to our AI pipeline was a single line of code, but it fundamentally changed the user experience. Instead of waiting five minutes for a response, the user either gets an instant result or a graceful fallback. Similarly, the decision to use AG Grid's cellStyle to color-code balances in red and green transformed the ledger from a dry spreadsheet into a visual, intuitive dashboard. We learned that the best engineering decisions are often the ones that eliminate friction for the end user, even if they add complexity under the hood.

What's next for FairShare

We built FairShare as a robust MVP that proves the core thesis: continuous data ingestion and real-time PayPal settlement can solve the invisible labor problem. The next phase is about moving from a hackathon demo to a production-grade platform. Here is our roadmap:

1. Native Hardware Integration (The IoT Layer) Right now, the smart plug feed is simulated through a hardware adapter interface. The immediate next step is to integrate directly with consumer IoT APIs—specifically TP-Link Kasa, Shelly, and Tuya smart plugs. This would allow FairShare to automatically attribute real-time electricity usage (kWh) to individual roommates without any manual intervention. We would also integrate with smart water flow meters to track water consumption at the appliance level.

2. Voice-First Invisible Labor Logging The 1-tap buttons for "Groceries" and "Mental Load" are a great start, but we want to go further. The next iteration will integrate a voice-note pipeline (using Whisper or Speechmatics). A roommate could simply say, "I bought toilet paper and cleaned the kitchen for two hours," and the AI would parse the audio, categorize the labor, and log it in the ledger. This reduces logging friction to near-zero—just speak and walk away.

3. Bank-Grade Payment Rails & Open Banking While PayPal handles the settlement beautifully, the next step is to integrate Open Banking APIs (like Plaid in the US or TrueLayer in the UK). This would allow FairShare to read actual bank transactions and automatically attribute utility bills and rent payments to the correct roommates without them ever needing to upload a PDF. The PayPal layer remains the execution engine; Open Banking becomes the data ingestion engine.

4. Expanding Beyond Roommates (B2B Pivot) The FairShare engine is fundamentally a continuous, usage-aware settlement system. The same architecture that settles electricity bills between roommates can be applied to co-working spaces, student dormitories, and small businesses that share resources. We see a clear B2B pivot opportunity: property management companies could deploy FairShare as a value-add for their tenants, reducing the administrative burden of shared utility billing.

5. Financial Health Dashboard & Predictive Analytics Once we have months of continuous usage data, we can build predictive models. The app could alert a household: "Your electricity usage is trending 20% higher than last month. Based on your current split rule, Alex will owe £15 more than usual in November." This moves FairShare from a reactive settlement tool to a proactive financial planning tool for households.

6. Expanding the Currency & Regulatory Footprint Currently, the app is hardcoded to GBP for the demo, but the architecture is currency-agnostic. The next step is to support multi-currency households (common in international cities like London or Dubai) and implement local tax and invoicing compliance for PayPal's global markets.

Built With

• 1.-next.js
• 10.-paypal-rest-api
• 11.-paypal-invoicing
• 12.-paypal-payouts
• 13.-render
• 14.-node.js
• 15.-ai
• 16.-machine-learning
• 17.-fintech
• 18.-hackathon
• 19.-iot
• 2.-react
• 20.-ocr
• 21.-multimodal-ai
• 22.-serverless
• 23.-rest-api
• 24.-oauth2
• 3.-typescript
• 4.-tailwind-css
• 5.-ag-grid
• 6.-google-gemini
• 7.-openrouter
• 8.-openai
• 9.-paypal