Skip to content

Commit d4f48ce

Browse files
author
root
committed
docs: expand README and add contributing guide
1 parent 146ceb5 commit d4f48ce

2 files changed

Lines changed: 185 additions & 125 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Contributing to FairShare
2+
3+
Thanks for helping improve FairShare. This guide covers setup, workflow, and contribution standards.
4+
5+
## Setup
6+
1. Install dependencies:
7+
```
8+
pnpm install
9+
```
10+
2. Create environment files:
11+
```
12+
cp .env.example .env
13+
cp apps/mobile/.env.example apps/mobile/.env
14+
```
15+
3. Start local services:
16+
```
17+
docker-compose up -d
18+
```
19+
4. Run apps:
20+
```
21+
pnpm dev
22+
```
23+
24+
## Project Structure
25+
- `apps/backend`: NestJS API
26+
- `apps/web`: Next.js dashboard
27+
- `apps/mobile`: Expo app
28+
- `packages/shared-types`: shared types across apps
29+
30+
## Branching and Commits
31+
- Create a feature branch from `main`.
32+
- Keep commits focused and readable.
33+
- Use conventional commit style when possible:
34+
- `feat(scope): message`
35+
- `fix(scope): message`
36+
- `chore(scope): message`
37+
38+
## Code Style
39+
- TypeScript everywhere
40+
- Keep UI changes consistent with existing design tokens
41+
- Avoid introducing new dependencies unless necessary
42+
- Prefer shared types in `packages/shared-types`
43+
44+
## Testing
45+
Run what applies to your change:
46+
```
47+
pnpm lint
48+
pnpm test
49+
pnpm --filter web build
50+
```
51+
52+
## Pull Request Checklist
53+
- Changes compile and relevant tests pass
54+
- Screenshots for UI changes (web/mobile)
55+
- No secrets or credentials committed
56+
- Updated README/docs if behavior changed
57+
58+
## Reporting Issues
59+
When filing a bug, include:
60+
- Reproduction steps
61+
- Expected vs actual behavior
62+
- Logs or screenshots
63+
- App version and environment

‎README.md‎

Lines changed: 122 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -1,154 +1,151 @@
1-
# 💸 FairShare
1+
# FairShare
2+
3+
A production-grade monorepo for collaborative expense sharing across mobile, web, and backend services.
4+
5+
## Overview
6+
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.
7+
8+
## What Is Implemented
9+
10+
### Mobile app
11+
- Authentication, registration, and profile management
12+
- Group creation, member management, and invitations
13+
- Expense creation (equal, exact, percentage splits)
14+
- Expense details with receipt preview/upload flow
15+
- Group activity timeline with pagination
16+
- Settlement flow with UPI deep link and mark-paid
17+
- Theme switching (light, dark, system)
18+
19+
### Web dashboard
20+
- Authentication, registration, and session handling
21+
- Dashboard summary, recent activity, and quick actions
22+
- Group list and group detail views
23+
- Expense creation and receipt upload
24+
- Member invitations
25+
- Settlement suggestions with confirm flow
26+
- Activity timeline with group filtering and pagination
27+
- Profile and settings pages with light/dark/system theme
28+
29+
### Backend API
30+
- NestJS API with Prisma + Supabase/Postgres
31+
- BigInt-based split arithmetic for precise balances
32+
- Redis for background jobs and caching
33+
- S3 for receipt storage
34+
- JWT auth with refresh tokens
35+
- Stripe hooks (optional) and Sentry hooks (optional)
36+
37+
## Architecture
238

3-
**A Production-Grade Monorepo for Collaborative Expense Sharing.**
4-
5-
FairShare is a high-performance, full-stack solution designed for seamless expense tracking and settlement. Built with a modern TypeScript-first architecture, it provides a unified experience across mobile, web, and backend services.
6-
7-
---
8-
9-
## 🚀 Overview
10-
11-
FairShare simplifies communal living and shared adventures. Whether you're splitting rent with roommates or tracking costs on a group trip, FairShare provides the tools to handle complex splits, automate settlements via UPI, and maintain real-time visibility into balances.
12-
13-
### Key Highlights
14-
15-
- **Cross-Platform**: Expo-powered mobile app and Next.js web dashboard.
16-
- **Robust Backend**: Scalable NestJS microservice with Prisma and Supabase.
17-
- **Financial Integrity**: High-precision BigInt arithmetic for accurate penny-perfect splits.
18-
- **Production Ready**: Fully Dockerized, Terraform-orchestrated, and CI/CD-integrated.
19-
20-
---
21-
22-
## 🛠 Tech Stack
23-
24-
### Backend
25-
26-
- **Framework**: NestJS (TypeScript strict)
27-
- **Database**: PostgreSQL (Supabase) + Prisma ORM
28-
- **Caching**: Redis (BullMQ for async jobs)
29-
- **Storage**: AWS S3 (Receipts & Assets)
30-
- **Security**: JWT Rotation, Google OAuth, Helmet, CSRF Protection
31-
- **Observability**: Prometheus metrics + Sentry + OpenTelemetry
32-
33-
### Mobile
34-
35-
- **Framework**: Expo Router (React Native)
36-
- **Styling**: React Native Paper + Reanimated animations
37-
- **State/Networking**: Axios + Socket.io + TanStack Query (planned)
38-
- **Native Hooks**: Haptic feedback, Lottie animations, UPI Deep-linking
39-
40-
### Web
41-
42-
- **Framework**: Next.js
43-
- **Styling**: TailwindCSS + Framer Motion
44-
- **SEO**: Dynamic metadata & SSR optimized
45-
46-
---
47-
48-
## 📁 Project Structure
49-
50-
This project uses **Turborepo** and **pnpm** for workspace management:
51-
52-
```text
39+
```
5340
FairShare/
5441
├── apps/
5542
│ ├── backend/ # NestJS API Service
5643
│ ├── mobile/ # Expo / React Native App
5744
│ └── web/ # Next.js Marketing & Dashboard
5845
├── packages/
59-
│ └── shared-types/ # Shared TS interfaces & Zod schemas
60-
├── infra/ # Terraform modules (AWS ECS, RDS, S3)
61-
└── scripts/ # Automation & seeding utilities
46+
│ └── shared-types/ # Shared TS interfaces
47+
├── infra/ # Terraform modules
48+
└── scripts/ # Automation and seeding
6249
```
6350

64-
---
65-
66-
## 🚦 Getting Started
51+
## Prerequisites
52+
- Node.js 18+
53+
- pnpm 8+
54+
- Docker (for local Postgres and Redis)
55+
- Optional: AWS S3 bucket for receipts
6756

68-
### Prerequisites
57+
## Setup
6958

70-
- [Node.js](https://nodejs.org/) (v18+)
71-
- [pnpm](https://pnpm.io/) (v8+)
72-
- [Docker](https://www.docker.com/) (for local services)
73-
74-
### Installation
75-
76-
1. **Clone the repository**:
77-
78-
```bash
79-
git clone https://github.com/Arun-kushwaha007/FairShare.git
80-
cd FairShare
81-
```
82-
83-
2. **Install dependencies**:
84-
85-
```bash
86-
pnpm install
87-
```
88-
89-
3. **Environment Setup**:
90-
91-
Copy `.env.example` to `.env` in the root and within `apps/backend/`.
59+
### 1) Install dependencies
60+
```
61+
pnpm install
62+
```
9263

93-
```bash
94-
cp .env.example .env
95-
```
64+
### 2) Configure environment variables
65+
Create `.env` at the repo root (used by backend and shared tooling):
9666

97-
> [!IMPORTANT]
98-
> The backend requires several mandatory environment variables to bootstrap successfully. Ensure the following are set in `apps/backend/.env`:
99-
> - `SUPABASE_DATABASE_URL`: Your PostgreSQL connection string.
100-
> - `JWT_SECRET` & `JWT_REFRESH_SECRET`: Secure strings for token signing.
101-
> - `STRIPE_SECRET_KEY`: Required for the payments module (starts with `sk_test_`).
102-
> - `STRIPE_WEBHOOK_SECRET`: Required for processing payment events (starts with `whsec_`).
103-
> - `GOOGLE_CLIENT_ID` & `SECRET`: For OAuth integration.
67+
```
68+
cp .env.example .env
69+
```
10470

105-
4. **Start Development Services**:
71+
Required variables in `.env`:
72+
- `SUPABASE_DATABASE_URL`
73+
- `JWT_SECRET`
74+
- `JWT_REFRESH_SECRET`
75+
- `REDIS_URL`
76+
- `CORS_ORIGINS` (include web + Expo dev URLs)
10677

107-
```bash
108-
# Start DB, Redis via Docker
109-
docker-compose up -d
110-
111-
# Run all apps in dev mode (Turbo)
112-
pnpm dev
113-
```
78+
Optional but supported:
79+
- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `S3_BUCKET`
80+
- `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`
81+
- `SENTRY_DSN`, `EXPO_PUBLIC_SENTRY_DSN`
82+
- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
11483

115-
### 💻 Developing Locally
84+
Mobile app `.env` (used by Expo):
85+
```
86+
cp apps/mobile/.env.example apps/mobile/.env
87+
```
88+
Set:
89+
- `EXPO_PUBLIC_API_URL` (point to your API host, often your LAN IP)
90+
- `EXPO_PUBLIC_S3_BASE_URL` (optional, public S3 base URL)
11691

117-
You can also start specific services individually using the following commands from the root:
92+
Web app environment:
93+
- `FAIRSHARE_API_URL` or `NEXT_PUBLIC_API_URL`
94+
- Defaults to `http://localhost:3001/api/v1`
11895

119-
| Service | Command | Description |
120-
| :--- | :--- | :--- |
121-
| **All Service** | `pnpm dev` | Starts Backend, Mobile, and Web in parallel via Turbo. |
122-
| **Backend** | `pnpm dev:backend` | Starts the NestJS API with hot reload. |
123-
| **Mobile** | `pnpm dev:mobile` | Starts the Expo development server (Expo Go). |
124-
| **Web** | `pnpm dev:web` | Starts the Next.js development server. |
125-
| **Seeding** | `pnpm seed` | Populates the database with initial development data. |
126-
| **Building Mobile** | `pnpm mobile:build` | Triggers EAS build for production AAB/IPA. |
96+
### 3) Start local infrastructure
97+
```
98+
docker-compose up -d
99+
```
127100

128-
---
101+
### 4) Run services
102+
```
103+
# All apps in parallel
104+
turbo run dev --parallel
129105
130-
## 🔋 Core Features
106+
# Or individually
107+
pnpm dev:backend
108+
pnpm dev:web
109+
pnpm dev:mobile
110+
```
131111

132-
- **Advanced Split Logic**: Supports equal, exact, and percentage-based splits.
133-
- **Fast Settlements**: Greedy simplification algorithm to minimize total payments.
134-
- **Real-time Activity**: Live updates via WebSockets for group actions.
135-
- **Offline Resilience**: Mobile-first architecture with offline queuing for expense entry.
136-
- **Push Notifications**: Intelligent reminders for pending settlements via Expo.
112+
## Development Guide
137113

138-
---
114+
### Backend
115+
- API base URL: `http://localhost:3001/api/v1`
116+
- Seed data: `pnpm seed`
117+
- Ensure Redis and Postgres are running via Docker.
139118

140-
## 🚢 Infrastructure & Deployment
119+
### Web
120+
- Next.js dashboard and marketing pages
121+
- Theme is controlled via `data-theme` and local storage
122+
- Build: `pnpm --filter web build`
141123

142-
- **CI/CD**: GitHub Actions for automated type-checking, linting, and Playwright E2E testing.
143-
- **Cloud Hosting**: AWS ECS (Fargate) for backend, Vercel/Netlify for web, and EAS for mobile.
144-
- **IaC**: Terraform-managed VPC, ECS Cluster, RDS, and S3 buckets.
124+
### Mobile
125+
- Use Expo Go or a simulator
126+
- Make sure `EXPO_PUBLIC_API_URL` points to a reachable host
127+
- If using a device, replace `localhost` with your LAN IP
145128

146-
---
129+
## Useful Commands
147130

148-
## 📄 License & Documentation
131+
```
132+
pnpm dev # all apps
133+
pnpm dev:web # web only
134+
pnpm dev:backend # backend only
135+
pnpm dev:mobile # mobile only
136+
pnpm lint # lint all
137+
pnpm test # tests all
138+
pnpm e2e # Playwright
139+
pnpm format # Prettier
140+
```
149141

150-
Refer to [doc.md](doc.md) for detailed technical architecture and production launch notes.
142+
## Troubleshooting
143+
- If mobile cannot reach the API, use your LAN IP in `EXPO_PUBLIC_API_URL`.
144+
- If you see CORS errors, add the web and Expo URLs to `CORS_ORIGINS`.
145+
- Receipt upload requires a configured S3 bucket and credentials.
151146

152-
---
147+
## Contributing
148+
See `CONTRIBUTING.md` for workflow and standards.
153149

154-
*Developed with ❤️ by the FairShare Team.*
150+
## Documentation
151+
For architecture notes and deployment guidance, see `doc.md`.

0 commit comments

Comments
 (0)