Ajora

Run your ajo or esusu circle with clear contributions, agreed turns, and a shared record.

Ajora helps Nigerian savings circles keep track of money sent through their existing bank accounts. Organisers can see what each member has contributed, review instalments, and record payouts. Members can check the same history and confirm when their payout arrives.

Built for Zecathon 2025 by Team P4L.

Why Ajora

A rotating savings circle depends on people agreeing when to contribute and who collects next. When references, receipts, and payout updates are scattered across chats and spreadsheets, the organiser has to piece the record together.

Ajora brings that record into one place while your group continues making payments through its usual channels. The MVP focuses on existing circles of people who already know each other.

What you can do

Circle workflow	What Ajora records
Create and invite	Contribution amount, weekly or monthly schedule, rules, members, and payout order.
Agree before starting	Each member accepts the current agreement. Membership, order, or collection-account changes require fresh acceptance.
Contribute in instalments	Each payment has its own amount, reference, and review status. Totals use accepted amounts.
Reconcile contributions	Organisers confirm external receipts manually or approve exact reference-and-amount matches from the demo feed. A matched receipt cannot fund two payments.
Confirm payouts	An organiser reports a payout as sent. Its recipient confirms receipt or reports a problem; only receipt confirmation advances the round.
Keep the shared history	Agreement snapshots, payment decisions, corrections, and payout discrepancies remain visible.
Return and stay informed	Email/password or configured Google sign-in restores access to your circles; polling and refresh show updates. WhatsApp actions prepare invitations, reminders, and summaries for you to send.

Current status: Ajora is a working MVP with a simulated bank feed. Demo matches exercise reconciliation; they do not verify real bank payments. Live Mono integration is not implemented. Ajora does not collect, hold, or transfer money. Payment discrepancy flags add to the shared history; they do not automatically freeze payouts or resolve disputes.

Quick start

Python 3.11+ and Node.js 22+ are the recommended local setup. Run these commands from the repository root. You do not need bank credentials or an AI API key for the savings-circle flow.

Install the backend and frontend dependencies:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
npm --prefix web ci

Start the API:

.venv/bin/python -m uvicorn api.main:app --reload

In a second terminal, start the frontend:

npm --prefix web run dev

Open Ajora at localhost:3200. The API runs on port 8000; its interactive reference documents the endpoints. The frontend proxies API calls through the same origin.

To enable Google sign-in using the same SQLite accounts, follow Google Cloud setup.

With Docker Compose, you can instead run:

docker compose up --build

The containerised app opens at localhost:3000. Compose retains savings state in the api-state volume.

For GitHub deployments, follow Deploying Ajora: Vercel hosts the frontend, and Render's free plan runs the API. The included Blueprint requires Turso managed SQLite for hosted accounts and circle records; missing credentials fail instead of accepting writes to temporary local storage. Follow the backup and cutover steps in Durable savings on free hosting before switching an existing service. Pushing to the configured production branch triggers a fresh deployment; it does not migrate saved records.

Try a complete circle

1. Create an account with your display name, email, and a password of 15–128 characters.
2. Create a two-member circle. Configure the demo collection account to try matching.
3. Use a second browser profile to join with the invite code. Tabs in one browser share an identity.
4. Arrange payout turns, have both members accept the final agreement, and start.
5. Submit instalments using the demo feed's references and amounts, then approve the matches as organiser. For real external payments, check receipt outside Ajora before confirming manually.
6. Record a payout as sent. As its recipient, confirm receipt to advance the round.

See the full walkthrough for login, legacy profile recovery, discrepancy reporting, configuration, and browser tests.

Data and access

Local circle records live in AJORA_STATE_DIR/savings.sqlite3. SQLite stores membership, agreements, contributions, receipt allocations, payout records, account emails, Google account identifiers, salted password hashes, session and legacy recovery-key hashes, and the shared event history. No database server is required. The state directory defaults to the repository root; use a persistent volume and back it up when retaining records. Removing the Compose volume removes its saved records. Hosted savings can use the approved Turso managed SQLite service: set TURSO_DATABASE_URL and TURSO_AUTH_TOKEN together on the API. Turso becomes the authoritative savings store, and writes succeed only after remote commit; a remote failure never falls back to a local file. With both variables unset and AJORA_REQUIRE_REMOTE_SAVINGS unset or false, the API uses local SQLite. The Render Blueprint sets this guard to true, requiring remote configuration.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗