Rewrite project status with current stack and gaps

Author: root

doc.md

@@ -2,231 +2,96 @@
 
 Last updated: March 15, 2026
 
-## Overview
-
-FairShare is a monorepo expense-sharing application with:
-
-- A NestJS backend in `apps/backend`
-- An Expo React Native mobile app in `apps/mobile`
-- A web app workspace in `apps/web`
-- Shared TypeScript contracts in `@fairshare/shared-types`
-
-The project is beyond bootstrap stage. Core expense-sharing flows, settlements, notifications, receipts, realtime updates, and payment intent creation are implemented. Recent work has shifted toward reliability, idempotency, delivery safety, and production hardening. The repository is currently clean and aligned with `origin/main` as of March 15, 2026.
-
-## Infrastructure And Deployment
-
-- Monorepo managed with `pnpm` and Turbo
-- PostgreSQL accessed through Prisma
-- Redis used for cache invalidation and queue-related workflows
-- Socket.IO used for realtime updates
-- S3 integration present for receipt flows using AWS SDK v3 presigning
-- Stripe integration present for payment intents and webhooks
-- Sentry and OpenTelemetry hooks present in the backend
-
-Backend runtime characteristics:
-
-- Nest listens on `0.0.0.0`
-- Global API prefix is `/api/v1`
-- CORS is enabled from configured origins
-- Throttling, compression, helmet, cookie parsing, CSRF protection, and request logging are enabled
-
-## Backend Implementation
-
-### Implemented modules
-
-The backend currently wires these major modules:
-
-- Auth
-- Users
-- Groups
-- Expenses
-- Balances
-- Settlements
-- Simplify
-- Receipts
-- Notifications
-- Payments
-- Jobs
-- Activity
-- Realtime
-- Health
-- Observability
-- Redis
-- S3
-- Prisma
-
-### Implemented backend capabilities
-
-- User authentication and token-based login flows
-- Group creation and membership management
-- Expense creation, listing, update, deletion, and detail retrieval
-- Balance tracking and debt simplification support
-- Settlement creation between group members
-- Receipt upload URL generation
-- Activity logging for domain actions
-- Push token registration and notification delivery workflows
-- Stripe payment intent creation
-- Payment webhook handling that records successful payments as settlements
-- Realtime emission for group activity
-- Health and metrics endpoints
-
-### Recent backend fix
-
-A NestJS startup failure caused by a module cycle was resolved.
-
-Problem chain:
-
-- `SettlementsModule -> NotificationsModule -> JobsModule -> PaymentsModule -> SettlementsModule`
-
-Resolution:
-
-- `SettlementsModule` now uses `forwardRef(() => NotificationsModule)` so Nest can resolve the cycle during module initialization
-
-This restored a clean backend boot path.
-
-### Recent backend reliability work
-
-Additional backend hardening completed in the latest pass:
-
-- Migrated S3 presigned upload generation from AWS SDK v2 to AWS SDK v3
-- Added receipt upload URL coverage with service-level and HTTP-level tests
-- Hardened payment webhook processing so settlement creation happens before payment status is marked `succeeded`
-- Improved settlement idempotency handling for duplicate webhook delivery and unique-key races
-- Enforced Stripe signature presence when a webhook secret is configured
-- Added notification delivery retry backoff and automatic cleanup of invalid Expo push tokens
-
-## Frontend And UX
-
-### Mobile status
-
-The Expo mobile app already includes:
-
-- Login and registration
-- Group list and group detail flows
-- Group members view
-- Add expense and expense detail flows
-- Settlement flow
-- Activity screen
-- Profile and settings screens
-- Shared UI components for cards, buttons, avatars, skeleton states, empty states, and toasts
-- Zustand-based stores for auth, groups, expenses, and toast state
-- Service clients for auth, groups, expenses, settlements, realtime, and users
-
-Implemented mobile platform features:
-
-- API client with request logging and latency tracking
-- Bearer-token injection from secure storage
-- Realtime connection after authentication
-- Push token registration through `expo-notifications`
-- Offline POST queueing for selected write actions
-
-### Recent mobile fixes
-
-Recent development fixes addressed local runtime issues:
-
-- Removed the stale `apps/mobile/.env` override for `EXPO_PUBLIC_API_URL`
-- Stopped forcing the dead API host `http://10.111.154.142:3001/api/v1`
-- Restored local API host auto-detection from the Expo runtime host
-- Removed the `api.ts` <-> `offlineQueue.ts` require cycle
-- Refactored the offline queue so it receives a request executor from `api.ts` instead of importing the API client directly
-
-This makes local mobile networking more reliable as long as the device and backend machine are on the same reachable network.
-
-### Web status
-
-The web workspace exists in the monorepo, but backend and mobile appear to be the most actively implemented parts of the product at this stage. Web should be treated as secondary until a dedicated milestone or readiness target is documented.
-
-## Testing And CI
-
-Repository-level scripts include:
-
-- `pnpm lint`
-- `pnpm test`
-- `pnpm e2e`
-
-Recent validation used during current fixes:
-
-- `pnpm --filter backend lint`
-- `pnpm --filter backend build`
-- `pnpm --filter backend test -- receipts`
-- `pnpm --filter backend test -- payments settlements`
-- `pnpm --filter backend test -- notifications`
-- `pnpm --filter mobile exec tsc --noEmit`
-
-There are tests in both backend and mobile codebases. The latest backend pass added direct coverage for receipt URL generation, payment webhook idempotency, settlement idempotency behavior, and notification retry handling.
-
-## Logging And Observability
-
-Backend observability already includes:
-
-- Sentry initialization
-- OpenTelemetry startup and shutdown hooks
-- Request logging middleware
-- Domain logging around notifications and payments
-- Prometheus-style metrics infrastructure through `prom-client`
-
-Mobile development diagnostics currently include:
-
-- API base URL logging in development
-- Request, response, and error logging in the API client
-- API latency tracking
-
-## Environment And Secrets
-
-Backend environment configuration currently covers:
-
-- Port
-- CORS origins
-- Redis connection
-- PostgreSQL and Prisma access
-- Stripe secret and webhook configuration
-- S3 configuration
-- Sentry DSN
-
-Mobile environment configuration currently covers:
-
-- Optional `EXPO_PUBLIC_API_URL` override
-- Optional `EXPO_PUBLIC_SENTRY_DSN`
-
-Important local mobile networking behavior:
-
-- If `EXPO_PUBLIC_API_URL` is set, it overrides host auto-detection
-- If it is not set, the app derives the backend host from the Expo runtime host during local development
-- The phone or emulator and the backend machine must still be on the same reachable network
-
-## Current Status
-
-### Working now
-
-- Backend boots successfully
-- Core API surface for auth, groups, expenses, balances, settlements, receipts, notifications, payments, and activity is implemented
-- Prisma, Redis, realtime, and payment flows are integrated in the backend
-- Receipt upload URLs are generated through AWS SDK v3 presigning
-- Payment webhook settlement handling is idempotent at the settlement layer and safer under retry
-- Invalid Expo push tokens are removed automatically after permanent delivery failures
-- Mobile app can authenticate, navigate the core flows, register push tokens, connect to realtime, and use the offline queue
-
-### Partially complete
-
-- Push notifications are implemented, but full remote notification testing should use a development build instead of Expo Go
-- Payments are implemented at the intent and webhook level, with improved idempotency, but still need broader production validation
-- Web progress is less clearly advanced than backend and mobile
-
-## Known Gaps
-
-- Expo package versions are slightly out of sync with the installed SDK and still produce compatibility warnings
-- `expo-notifications` remote push support is limited in Expo Go
-- Local mobile networking remains environment-sensitive when LAN addressing changes
-- Receipt OCR and structured receipt parsing are not implemented yet
-- Smart split suggestion APIs and UI are not implemented yet
-- Mobile notification center and expanded offline retry UI are not implemented yet
-- Broader observability counters and tracing for expense, settlement, and webhook flows still need expansion
+## Snapshot
+- Monorepo with NestJS API, Expo mobile client, and a Next.js marketing site managed via Turbo + pnpm.
+- Core expense, settlement, receipt, notification, realtime, and payment primitives are implemented server-side with Prisma/PostgreSQL (Supabase URL) and Redis/BullMQ.
+- Mobile app ships full flows (auth, groups, expenses, settle-up, activity, profile/settings) with offline queueing, push tokens, realtime sockets, and UPI deep-link helper; UI built with React Native Paper + Reanimated.
+- Web app is currently a single-page marketing/landing experience with Framer Motion; no dashboard/auth wiring yet.
+- Observability (Sentry, OpenTelemetry, Prometheus metrics) and security hardening (helmet, throttling, CSRF on refresh, JWT + refresh cookies) are wired in backend startup.
+
+## Project Structure
+- apps/backend — NestJS service exposing REST + WebSocket APIs; background jobs via BullMQ.
+- apps/mobile — Expo Router/React Native client with feature screens and state stores (Zustand).
+- apps/web — Next.js 15 site styled with Tailwind + Framer Motion animations.
+- packages/shared-types — DTOs and response contracts shared across apps.
+- infra/terraform — Terraform skeleton for AWS (ECS, RDS, S3) deployment.
+
+## Backend (apps/backend)
+### Major modules & responsibilities
+- Auth: register/login/google, refresh tokens (httpOnly cookie), CSRF token endpoint.
+- Users: `GET /users/me`, `POST /users/push-token` to register Expo tokens.
+- Groups: CRUD-ish flows (`POST /groups`, `GET /groups`, `GET /groups/:id`, members, invite, per-user/group summaries).
+- Expenses: create/list/update/delete per group; pagination via cursor+limit; detail fetch.
+- Balances: `GET /groups/:id/balances` to expose pairwise balances.
+- Simplify: `GET /groups/:id/simplify` returns settlement suggestions (used by mobile settle-up).
+- Settlements: `POST /groups/:id/settlements` with optional `x-idempotency-key`.
+- Receipts: `POST /expenses/:id/receipt-url` returns presigned S3 upload URL and records receipt key.
+- Activity: user and group feeds with cursor pagination.
+- Payments: `POST /payments/create-intent` (Stripe PaymentIntent) and `POST /payments/webhook` (queues handling); settlements are recorded from successful webhooks.
+- Realtime: Socket.IO gateway with `join_group`/`leave_group` rooms; emits expense/settlement/group-member events per group.
+- Notifications: Expo push delivery via Redis pub/sub + BullMQ retries; invalid tokens are cleaned up.
+- Health/Observability: `/health` checks PostgreSQL + Redis; `/metrics` exposes Prometheus text; OpenTelemetry auto-instrumentation on boot.
+
+### Data model (Prisma)
+- Users with JWT/refresh tokens, push tokens, activities.
+- Groups with members (roles), expenses (splits), balances, settlements, receipts, invites, payments, activities.
+- Expenses store cent-precision totals plus per-user splits; receipts are 1:1 with expenses.
+- Settlements & payments support idempotency keys; payments map to Stripe PaymentIntents.
+
+### Integrations & infrastructure
+- PostgreSQL via `SUPABASE_DATABASE_URL`.
+- Redis for queues + pub/sub + throttling state.
+- AWS S3 (AWS SDK v3) for receipt uploads (presigned PUT URLs).
+- Stripe (v18 SDK) for PaymentIntents; webhook signature enforced when `STRIPE_WEBHOOK_SECRET` set.
+- Google OAuth via `passport-google-oauth20` alongside email/password.
+- Expo push notifications via `expo-server-sdk`.
+- Security middleware: helmet, compression, cookie-parser, CSRF on refresh/csrf-token routes, Nest ValidationPipe (whitelist/forbid), global throttling, CORS allowlist.
+
+### Background jobs (BullMQ)
+- Notification delivery with exponential backoff and invalid-token cleanup.
+- Receipt processing placeholder queue hook (currently enqueues on presign, no downstream worker in repo).
+- Payment webhook handling queued with retries to shield Stripe endpoint.
+
+### Testing
+- Unit/integration Jest suites for activity, balances, expenses (service + integration), settlements (service + integration), receipts (service + integration), payments, simplify, users, notifications.
+
+## Mobile (apps/mobile)
+- Stack: Expo SDK 54, React Native 0.81, React Navigation, React Native Paper, Reanimated, Lottie, Zustand stores, Axios client, Socket.IO client, Expo Notifications, SecureStore, NetInfo.
+- UX flows: onboarding (login/register), group list/detail, members, add expense, expense detail, activity feed, settle-up suggestions, profile, settings, toasts, skeleton placeholders.
+- Offline: SecureStore-backed offline POST queue with automatic flush when connectivity returns; queues group expense creation, settlements, and invites.
+- Networking: Axios client auto-injects bearer token from SecureStore; base URL auto-derives from Expo host or `EXPO_PUBLIC_API_URL`; logs in dev; latency tracked; retry queue marks requests with `x-offline-retry` to avoid loops.
+- Realtime: connects to Socket.IO after auth for group events.
+- Push: registers device tokens and posts to `/users/push-token`.
+- Payments/settle-up UX: uses simplify suggestions; triggers UPI deep links for payers then marks settlement via API (does not yet surface Stripe PaymentIntent flow in-app).
+- Visuals: gradient/neo styling, animations on hero cards/actions, Avatar initials, haptic feedback hooks present.
+- Tests: basic Jest + testing-library specs for login, group list, add expense screens; TypeScript lint via `tsc --noEmit`.
+
+## Web (apps/web)
+- Next.js 15 single-page marketing site with Framer Motion animations, Lucide icons, Tailwind utility styles.
+- Sections: hero CTA, feature grid, comparison table, FAQ/dev log, newsletter form, footer links.
+- No auth or API wiring yet; currently a static experience suitable for marketing/landing only.
+
+## Shared Types (packages/shared-types)
+- Zod/TypeScript DTOs for auth payloads, expenses, balances, settlements, receipts, activity feeds, payments, notifications; consumed by backend controllers and mobile client.
+
+## DevOps & Tooling
+- Scripts: `pnpm dev|dev:backend|dev:mobile|dev:web`, `pnpm build`, `pnpm lint`, `pnpm test`, `pnpm e2e` (Playwright), `pnpm seed`.
+- Docker: backend Dockerfile; `docker-compose.yml` for local Postgres/Redis/S3? (check services before use).
+- Monitoring: Sentry DSN + OTEL hooks; Prometheus metrics endpoint.
+- Infra: Terraform stubs for AWS ECS/RDS/S3; CI assumed via GitHub Actions (see README claim) though pipeline files not present in repo root.
+
+## Known Gaps / Risks
+- Web app is marketing-only; product dashboard, auth, and API integration are not implemented.
+- Payments: mobile flow currently bypasses Stripe; settles via UPI link + manual settlement API. Stripe PaymentIntent UX is not exposed to clients yet.
+- Receipt processing queue lacks worker implementation; uploads are stored but no OCR/parsing pipeline exists.
+- Offline queue can replay POSTs without deduplication beyond backend idempotency keys; ensure idempotency keys are supplied for settlements/payments when adding clients.
+- Expo SDK 54 with React Native 0.81/React 19 stack may emit peer warnings; verify compatibility before release builds.
+- CI configuration for lint/test/e2e is referenced but not included in the repo snapshot.
 
 ## Next Steps
-
-1. Align Expo package versions with the installed SDK.
-2. Validate login, expense, settlement, payment, and notification flows end to end on a real device and a development build.
-3. Add receipt OCR processing and structured receipt item storage.
-4. Add smart split suggestion APIs and mobile UI.
-5. Expand observability counters and tracing for expense creation, settlement creation, and webhook processing.
-6. Clarify the target scope and milestone for the web workspace.
+1. Decide on in-app payment path: surface Stripe PaymentIntent client flow or keep UPI-only and disable PaymentIntent endpoint if unused.
+2. Implement receipt-processing worker (OCR or at least validation) for queued jobs; expose receipt retrieval in UI.
+3. Build authenticated web dashboard (groups/expenses/settlements) reusing shared-types + backend APIs.
+4. Add end-to-end tests (Playwright) for critical flows: auth, expense creation, settlement, receipt upload.
+5. Tighten mobile offline/idempotency by attaching idempotency keys and surfacing retry status to users.
+6. Add CI pipeline files (GitHub Actions) to run lint/test/build on PRs and publish metrics artifacts.