Circlo: SHG for Gen Z
A working, demo-ready prototype of Community Credit Circles for Students and Young Adults: small invite-only groups of verified people who pool contributions in a ledger, vote on loans, lend to each other by UPI, and see every rupee. UPI, eKYC, AutoPay and the NBFC-P2P partner are simulated. No real money moves. Circlo is a connector and a ledger only; it never holds a wallet.
Run it
npm install
npm run seed # creates circlo.db with 17 users, 5 circles, 11 loans, 131 ledger entries
npm run dev # http://localhost:3000
Other commands: npm run build · npm start · npm test (67 unit and lifecycle tests) · npm run test:e2e (Playwright smoke tests; builds nothing, so run npm run build first).
Needs Node 20+. Set CIRCLO_DB to use a different database file.
Demo in 2 minutes
Open the welcome page and tap a persona (or log in with the phone and any 6-digit code; the demo OTP is 123456).
| Persona | Phone | What to try |
|---|
| Ananya, student borrower | 9876500001 | Vote on Sneha's request; her own instalment is due in ~2 days; set up AutoPay |
| Vikram, circle admin / lender | 9876500002 | Pay his UPI share to Priya; edit rules; switch Compliance Mode; Circle Premium |
| Imran, young pro / outside borrower | 9876500003 | AutoPay loan in another circle; borrow as a vetted outsider |
| Platform admin | 9876500000 | Same app; Pilot Metrics, Revenue, Projections under Profile |
Use the account menu (top right) to switch persona at any time. Seeded circles show: a closed loan, a restructured loan, an overdue loan with a late penalty, a defaulted loan with lender loss shares, an open vote, and an approved loan awaiting UPI payments.
Deploy on Vercel (demo)
Import the GitHub repo in Vercel. vercel.json already sets the build to npm run seed && npm run build, so the demo database is created at build time and bundled with the app. Optional: set CIRCLO_SECRET to any long random string (signs login cookies and the signup KYC token).
Vercel's disk is read-only and temporary, so the app copies the seeded database to /tmp. Changes people make on the live site are kept only while that server instance stays warm and reset when it recycles, and different instances can show different changes. That is fine for a demo; for real use, move the database to a hosted one (for example Turso or Postgres) or host on a service with a persistent disk.
What is where
app/ Next.js App Router screens ((public) welcome, login, signup, explainers, legal; (app) the signed-in product)lib/domain/ pure, unit-tested rules: money, EMI, voting, risk score, exposure, penalties, risk sharing, ledger totalslib/core/ business operations on the database (create circle, request loan, vote, pay, repay, restructure, default, sweep)lib/services/ the simulated eKYC, UPI and partner-escrow behind interfaces (swap for real providers)lib/db/ Drizzle schema, migrations, and the seed (which replays history through the real functions on a fake clock)tests/ unit and lifecycle tests · e2e/ Playwright smoke tests
See DECISIONS.md for why things are built the way they are, and FEATURE_MAP.md for how each section of the business description maps to the product.
Honest limits
Prototype only: simulated payments and identity, SQLite storage, placeholder legal text, no real notifications (in-app only), English only (a string hook exists for Hindi and Telugu). Not legal or financial advice. Lending carries risk of loss.
