Skip to content

README.md

Latest commit

 

History

History
158 lines (129 loc) · 4.5 KB

README.md

File metadata and controls

158 lines (129 loc) · 4.5 KB
Raw

FairShare

A production-grade monorepo for collaborative expense sharing across mobile, web, and backend services.

Overview

FairShare simplifies shared living and group travel by providing accurate splits, real-time activity, and fast settlements. This repository contains a fully wired backend API, an Expo-powered mobile app, and a Next.js web dashboard.

What Is Implemented

Mobile app

  • Authentication, registration, and profile management
  • Group creation, member management, and invitations
  • Expense creation (equal, exact, percentage splits)
  • Expense details with receipt preview/upload flow
  • Group activity timeline with pagination
  • Settlement flow with UPI deep link and mark-paid
  • Theme switching (light, dark, system)

Web dashboard

  • Authentication, registration, and session handling
  • Dashboard summary, recent activity, and quick actions
  • Group list and group detail views
  • Expense creation and receipt upload
  • Member invitations
  • Settlement suggestions with confirm flow
  • Activity timeline with group filtering and pagination
  • Profile and settings pages with light/dark/system theme

Backend API

  • NestJS API with Prisma + Supabase/Postgres
  • BigInt-based split arithmetic for precise balances
  • Redis for background jobs and caching
  • S3 for receipt storage
  • JWT auth with refresh tokens
  • Stripe hooks (optional) and Sentry hooks (optional)

Architecture

FairShare/
├── apps/
│   ├── backend/      # NestJS API Service
│   ├── mobile/       # Expo / React Native App
│   └── web/          # Next.js Marketing & Dashboard
├── packages/
│   └── shared-types/ # Shared TS interfaces
├── infra/            # Terraform modules
└── scripts/          # Automation and seeding

Prerequisites

  • Node.js 18+
  • pnpm 8+
  • Docker (for local Postgres and Redis)
  • Optional: AWS S3 bucket for receipts

Setup

1) Install dependencies

pnpm install

2) Configure environment variables

Create .env at the repo root (used by backend and shared tooling):

cp .env.example .env

Required variables in .env:

  • SUPABASE_DATABASE_URL
  • JWT_SECRET
  • JWT_REFRESH_SECRET
  • REDIS_URL
  • CORS_ORIGINS (include web + Expo dev URLs)

Optional but supported:

  • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, S3_BUCKET
  • STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
  • SENTRY_DSN, EXPO_PUBLIC_SENTRY_DSN
  • GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET

Mobile app .env (used by Expo):

cp apps/mobile/.env.example apps/mobile/.env

Set:

  • EXPO_PUBLIC_API_URL (point to your API host, often your LAN IP)
  • EXPO_PUBLIC_S3_BASE_URL (optional, public S3 base URL)

Web app environment:

cp apps/web/.env.example apps/web/.env.local
  • FAIRSHARE_API_URL for server-side web requests
  • NEXT_PUBLIC_API_URL for client-side web requests
  • FAIRSHARE_S3_BASE_URL and NEXT_PUBLIC_S3_BASE_URL for receipt previews when using S3
  • Defaults to http://localhost:3001/api/v1 when API vars are unset

3) Start local infrastructure

docker-compose up -d

4) Run services

# All apps in parallel
turbo run dev --parallel

# Or individually
pnpm dev:backend
pnpm dev:web
pnpm dev:mobile

Development Guide

Backend

  • API base URL: http://localhost:3001/api/v1
  • Seed data: pnpm seed
  • Ensure Redis and Postgres are running via Docker.

Web

  • Next.js dashboard and marketing pages
  • Theme is controlled via data-theme and local storage
  • Auth tokens for the web app are stored only in httpOnly cookies managed by apps/web/app/api/auth/*, apps/web/src/lib/backend.ts, and apps/web/middleware.ts
  • localStorage is not part of the web auth flow
  • Build: pnpm --filter web build

Mobile

  • Use Expo Go or a simulator
  • Make sure EXPO_PUBLIC_API_URL points to a reachable host
  • If using a device, replace localhost with your LAN IP

Useful Commands

pnpm dev             # all apps
pnpm dev:web         # web only
pnpm dev:backend     # backend only
pnpm dev:mobile      # mobile only
pnpm lint            # lint all
pnpm test            # tests all
pnpm e2e             # Playwright
pnpm format          # Prettier

Troubleshooting

  • If mobile cannot reach the API, use your LAN IP in EXPO_PUBLIC_API_URL.
  • If you see CORS errors, add the web and Expo URLs to CORS_ORIGINS.
  • Receipt upload requires a configured S3 bucket and credentials.

Contributing

See CONTRIBUTING.md for workflow and standards.

Documentation

For architecture notes and deployment guidance, see doc.md.