Ajo

Ajo is a decentralized savings-group platform built on Stellar's Soroban smart contracts. It brings the traditional "Ajo" / "susu" / Rotating Savings and Credit Association (ROSCA) model on-chain, letting communities pool and cycle contributions with full transparency, auditable transaction history, and no central custodian.

Overview

The project is a monorepo with four independently deployable parts:

Component	Path	Stack
Smart contracts	contracts/ajo	Rust / Soroban
API server	backend	Node.js, Express, TypeScript, Prisma
Web app	frontend	Next.js 14 (App Router), TypeScript, Tailwind CSS
Mobile app	mobile	React Native / Expo

Features

• Create and manage savings groups with configurable contribution rules
• Member onboarding, invitations, and role management
• Scheduled contributions and automated payout tracking
• Fully auditable on-chain transaction history
• Dispute filing, voting, and admin arbitration
• Group analytics and gamification (achievements, leaderboards)
• Stellar wallet integration (Freighter and others)
• Multi-language support (English, Spanish, French, Portuguese, Arabic, Swahili, Chinese)

Getting Started

Prerequisites

• Node.js 20+
• Rust 1.70+ and the Stellar CLI
• Git

Installation

git clone https://github.com/Ajo-contrib/soroban-ajo.git
cd soroban-ajo

# Install root, frontend, and backend dependencies
npm run install:all

# Mobile has its own dependency tree
cd mobile && npm install

Configure environment variables

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env.local
cp mobile/.env.example mobile/.env

Fill in your Stellar RPC URL and deployed contract ID in each file (see Environment Variables below).

Run the smart contracts

cd contracts/ajo
stellar contract build
cargo test

To deploy to testnet, use the helper script from the repo root:

scripts/deploy_testnet.sh

This provisions a deployer identity, builds and optimizes the contract, deploys to Stellar testnet, and writes the resulting contract ID to contract-id.txt.

Run the backend and frontend

# From the repo root — runs both concurrently
npm run dev

• Backend API: http://localhost:3001 (interactive API docs at /api-docs)
• Frontend: http://localhost:3000

Or run each independently:

npm run dev:backend    # Express on :3001
npm run dev:frontend   # Next.js on :3000

Run the mobile app

cd mobile
npm start

Environment Variables

backend/.env

NODE_ENV=development
PORT=3001
FRONTEND_URL=http://localhost:3000
DATABASE_URL=postgresql://user:password@localhost:5432/ajo
JWT_SECRET=<your_jwt_secret>
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
SOROBAN_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
SOROBAN_CONTRACT_ID=<your_contract_id>

frontend/.env.local

NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_SOROBAN_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
NEXT_PUBLIC_SOROBAN_CONTRACT_ID=<your_contract_id>
NEXT_PUBLIC_API_URL=http://localhost:3001

See backend/.env.example and frontend/.env.example for the complete list of optional integrations (Stripe, PayPal, email, SMS, etc.).

Testing

npm run type-check      # TypeScript, frontend + backend
npm run lint             # ESLint, frontend + backend
npm run test:contracts   # Rust contract tests

Deployment

• Contracts: stellar contract deploy against testnet or mainnet (see Smart Contract Documentation)
• Backend: any Node.js host (Railway, Render, Fly.io, AWS/GCP/Azure) — npm run build && npm start
• Frontend: Vercel — set the project's Root Directory to frontend

See docs/DEPLOYMENT.md for full deployment instructions.

Documentation

• Developer Onboarding
• Architecture Decision Records
• Smart Contract Documentation / Integration Guide
• i18n Architecture
• User Guide / Tutorials
• Frontend README · Backend README · Mobile README

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

License

Distributed under the terms of the MIT License.

Resources

• Stellar Developer Docs
• Soroban Docs
• Next.js Documentation

Support

For questions, bug reports, or feature requests, please open an issue.