Compences

समुदाय — plan together, participate together, spend transparently.

A platform for the events a residential community runs: Ganesh Chaturthi, a sports day, a cultural evening. Each one carries its own people, activities, checklist, fund and public ledger.

One codebase, four surfaces:

Surface	What it is
Web	Next.js 16 app — resident portal and admin console
Mobile	Expo / React Native — iOS and Android from the same source
WhatsApp	A bot for the fund, notices, activities and your own tasks
API & MCP	REST for integrations, MCP so an AI assistant can use it as tools

Nobody joins by guessing a URL. An admin shares the Society ID; a resident signs in with Google, picks their flat, and the admin approves them. For people the committee already knows, an invite code skips the waiting step.

---

How it is put together

apps/
  web/        Next.js 16 (App Router) — UI, REST API, MCP server, WhatsApp webhook
  mobile/     Expo SDK 57 + expo-router — iOS, Android
packages/
  core/       Domain rules: roles, event maths, zod schemas, WhatsApp parsing
  supabase/   Typed Supabase clients + generated database types
  config/     Shared TypeScript config
supabase/
  migrations/ Schema, RLS policies and RPCs
  tests/      A Supabase shim + the RLS test suite
scripts/      db-test.sh, smoke-test.sh, gen-db-types.mjs, seed.ts

The shape of it

Event
├── Checklist        tasks with owner and due date → drives "Readiness %"
├── Fund             target, contributions, contributor count
├── Activities       cultural acts residents sign up to perform in
├── Volunteer roles  jobs residents sign up to do
├── Expenses         vendor, amount, attached bill, approval trail
├── Vendors          marketplace listings chosen to supply the event
└── Closure          surplus rule → published transparency report

Marketplace          what residents make, teach and sell each other —
                     listings with a phone and a photo, star ratings, reviews

Where the rules actually live

In PostgreSQL. Every table has row-level security; the web app, the mobile app, the API and the bot all go through it. The TypeScript in packages/core/src/roles.ts decides what to show a user — it is not what stops them. That separation is tested rather than asserted: supabase/tests proves that

• a resident sees every approved rupee of spending, with the vendor and the bill, and does not see an expense still under review;
• a resident's own contribution amount is private while the society total and contributor count are public;
• nobody approves an expense they filed themselves;
• a closed event's ledger cannot be reopened or edited;
• moving money between funds needs a resident vote that clears a threshold, and writes an audit row in the same transaction as the deciding vote;
• one member, one vote — and a ballot is readable only by the person who cast it;
• nothing leaks between societies;
• a marketplace listing shows the number its seller typed, never the private one on their profile, and nobody reviews their own listing.

Two places bypass RLS on purpose, both server-side only:

• API-key requests — there is no Supabase user behind an AI agent's key, so the service role is used and every query is scoped by hand. All of those queries live in one file, apps/web/src/lib/api/resources.ts, so the scoping cannot be forgotten piecemeal.
• The WhatsApp webhook — a phone number is not a session. lib/whatsapp/bot.ts resolves the sender to one society first and scopes everything to it.

---

Getting it running

1. Create a Supabase project

Anywhere you like — supabase.com or a local stack. You need the project URL, the anon key and the service-role key.

2. Apply the schema

pnpm dlx supabase link --project-ref <your-ref>
pnpm db:push          # applies supabase/migrations in order
pnpm db:status        # SUPABASE_DB_URL=… — names any migration the database is missing

Deploys and migrations travel separately: the web app ships when main moves, the schema waits for db:push. The Migrations workflow runs db:status against production on every push to main and once a day, so a migration left behind turns a check red instead of turning a feature into "Something went wrong". It needs a SUPABASE_DB_URL repository secret, and fails rather than skips without one.

Use the Session pooler string for that secret — Supabase dashboard → Connect → Session pooler:

postgresql://postgres.<ref>:<password>@aws-<n>-<region>.pooler.supabase.com:5432/postgres

Not the direct db.<ref>.supabase.co one. It resolves to IPv6 only, and GitHub Actions runners are IPv4, so the job would fail on the network rather than on the schema.

3. Turn on Google sign-in

In the Supabase dashboard → Authentication → Providers → Google, add your Google OAuth client ID and secret. In the Google Cloud console, add this redirect URI:

https://<your-project-ref>.supabase.co/auth/v1/callback

Then under Authentication → URL Configuration, add your site URL and http://localhost:3000/** to the redirect allow-list. Email magic links are built but switched off (EMAIL_SIGN_IN_ENABLED in each app's lib/sign-in-options.ts); turning them on needs no Supabase setup.

4. Configure and run

cp .env.example apps/web/.env.local     # fill in the Supabase values
cp .env.example apps/mobile/.env        # the EXPO_PUBLIC_ ones
pnpm install
pnpm dev

The web app is on http://localhost:3000; pnpm --filter @compences/mobile start opens the Expo dev server.

This is the beginning of the README. Read the rest at the original. Read the full README ↗