ShareSquare

Current release: v1.0.0 (MVP) — see agentdocs/sharesquare-v1/RELEASE-1.0.md and the archived project context in agentdocs/sharesquare-v1/context.json.

A browser-first expense tracking PWA for friends, roommates, and families. ShareSquare records shared expenses, calculates “who owes whom,” and supports settlements — with Supabase for auth and data, and a Vite + React SPA.

Living documentation (spec-it, scoped)

The repo uses scoped agentdocs: a root registry plus one folder per product line.

Path	Role
agentdocs/context.json	Workspace registry — active_project and projects[] (spec-it scoped mode)
agentdocs/sharesquare-v1/	Frozen v1.0 docs (spec, design, requirements, tasks, release notes, task index)
agentdocs/sharesquare-v1.1/	Active v1.1 cycle — Phase SPEC stubs; this is where new work is specified first

Resolve {P} as agentdocs/<active_project>/ using the root registry.

Target architecture (v1.0 shipped)

Layer	Technology
Build / app	Vite 6, React 19, TypeScript 5, react-router-dom 7
Styling	Tailwind CSS 4
Backend / DB	Supabase (Postgres + Auth + RLS)
Client	@supabase/supabase-js
PWA	vite-plugin-pwa (Workbox); online-first data, precached shell/assets
Testing	Jest + React Testing Library

Implementation note: The app shell is Vite + React. Data uses Supabase repositories when VITE_USE_SUPABASE_REPOS=true; IndexedDB (Dexie) remains available for local/demo mode. For v1.0 behavior and schema, use agentdocs/sharesquare-v1/; v1.1 will extend or revise via the new cycle.

Features (product)

• Supabase Auth — Sign-in via providers and/or magic link configured in the Supabase project (no separate client-only Google OAuth SDK requirement)
• Group management — Create groups, share invite codes stored in Postgres (groups.invite_code)
• Expense tracking — Equal, exact, and percentage splits; integer cents in the data layer
• Balances & debt simplification — Per-group and cross-group views; greedy net-balance simplification
• Settlements — Record payments between members
• Activity feed — Chronological actions across groups
• JSON export/import — Portability via repositories
• PWA — Installable; core data operations require network for MVP

PWA behavior (online-first)

vite-plugin-pwa generates a Workbox service worker on npm run build that precaches the app shell and static assets (faster loads, install prompt). Expense and group data are not offline-first in MVP: CRUD still expects network access once Supabase is wired. See public/manifest.json for install metadata.

Getting started

Prerequisites

• Node.js 18+
• npm 9+
• A Supabase project (URL + anon key) once the stack migration is applied — see supabase/README.md for running SQL migrations

Installation

git clone <repo-url>
cd sharesquare
npm install

Development

npm run dev

Default dev URL is typically http://localhost:5173 (Vite). If you see .next/ or out/ in the repo root from an older Next.js build, you can delete those folders; this app is Vite-only.

Environment

Canonical variable names and placeholders live in .env.example. Copy it to .env.local (or .env) and set:

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY
• VITE_USE_SUPABASE_REPOS — set to true, TRUE, or 1 to use the shared Supabase anon client for all repositories; leave false or unset to keep IndexedDB (Dexie) for local/offline-first dev. (Case-insensitive true matches how some editors save env files.)

With Supabase Auth (Google / magic link) and repos still on IndexedDB, the app derives your profile from the auth session and still stores groups/expenses in the browser until you set VITE_USE_SUPABASE_REPOS=true.

Never commit secrets or the service role key.

After filling .env.local / .env, run npm run verify:supabase-env to confirm URL + anon key match the expected ShareSquare project (override with EXPECTED_SUPABASE_PROJECT_URL if needed). See agentdocs/sharesquare-v1/supabase-setup-checklist.md §6 for MCP vs dashboard vs browser checks.

Google / magic link: With a real Supabase project URL (not the Jest placeholder), the login page shows Sign in with Google, which uses supabase.auth.signInWithOAuth. Configure Site URL, redirect allow list, and Google OAuth credentials in the Supabase dashboard — see supabase/README.md § Supabase Auth (dashboard). For local demo without a project, use Quick Start (Demo Mode).

Common scripts

Command	Description
npm run dev	Development server
npm run build	Production build
npm test	Unit tests
npm run typecheck	TypeScript check
npm run lint	ESLint
npm run format	Prettier (write)
npm run verify:supabase-env	Check VITE_SUPABASE_* for Auth (no secrets printed)

Project structure (v1.0)

Aligned with agentdocs/sharesquare-v1/design.md §8:

index.html
src/
  main.tsx, App.tsx       # Vite entry + React Router
  pages/                  # Route-level screens
  components/
  layouts/
  repositories/
    interfaces/
    supabase/             # Supabase-backed implementations + client.ts
  services/
  contexts/
  hooks/
  types/
  utils/
  constants/
supabase/migrations/      # SQL + RLS

Architecture

Pages → Hooks → Repository interfaces → Supabase repositories → Postgres (RLS)
             → Services (pure logic: balances, debt simplification, import/export)

Spec-driven development

Document	Purpose
agentdocs/context.json	Registry — active_project, list of slugs
agentdocs/sharesquare-v1/spec.md	v1.0 product spec (archived line)
agentdocs/sharesquare-v1/requirements.md	v1.0 requirements (33 REQs)
agentdocs/sharesquare-v1/design.md	v1.0 technical design
agentdocs/sharesquare-v1/tasks.md	v1.0 tasks (60, complete)
agentdocs/sharesquare-v1/context.json	v1.0 machine-readable release state
agentdocs/sharesquare-v1.1/*	v1.1 — new spec-it cycle (start with spec.md + requirements.md)

License

Private project.