Ajo - Decentralized Savings Groups

A blockchain-based savings group platform built on Stellar/Soroban, enabling communities to create and manage traditional "Ajo" or "Rotating Savings and Credit Associations" (ROSCAs) with full transparency and security.

📖 Documentation

Interactive documentation site: Run npm run dev:docs and visit http://localhost:3000

• Getting Started Guide
• API Reference - Interactive Swagger UI
• Architecture Overview
• Smart Contracts

🏗 Project Structure

drips_maintener/
├── frontend/          # Next.js web application
│   └── src/
│       ├── app/       # Next.js pages (App Router)
│       ├── components/
│       ├── hooks/
│       └── services/
├── backend/           # Node.js/Express API server
│   └── src/
│       ├── routes/    # API routes
│       ├── controllers/
│       ├── services/  # Soroban integration
│       └── middleware/
├── contracts/         # Soroban smart contracts (Rust)
│   └── ajo/          # Main Ajo contract
├── documentation/     # All project documentation
└── package.json      # Monorepo root config

🚀 Quick Start

Prerequisites

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

Monorepo Setup

# Clone repository
git clone <repo-url>
cd drips_maintener

# Install all dependencies (frontend + backend)
npm run install:all

# Or install individually:
npm install           # Root dependencies
cd frontend && npm install
cd ../backend && npm install

Smart Contracts (Rust/Soroban)

cd contracts/ajo

# Build contract
stellar contract build

# Run tests
cargo test

# Deploy (with Stellar CLI configured)
stellar contract deploy --wasm target/wasm32-unknown-unknown/release/ajo.wasm

Testnet Deployment (recommended)

Use the helper script to deploy the contract to Stellar testnet:

# From repo root
scripts/deploy_testnet.sh

What it does:

• Ensures Soroban CLI, Rust, and testnet network config exist
• Generates a deployer identity (if missing) and prompts you to fund it via friendbot
• Builds and optimizes the contract
• Deploys to testnet and writes the contract ID to contract-id.txt
• Prints next steps and an explorer link

See the full walkthrough in demo/demo-script.md.

Troubleshooting

• If deployment fails with funding errors: fund the deployer shown in the script output via https://friendbot.stellar.org?addr=<address>, then re-run.
• If soroban can't find testnet: the script re-adds it, or you can run
  soroban network add --global testnet --rpc-url https://soroban-testnet.stellar.org:443 --network-passphrase "Test SDF Network ; September 2015".

Backend API (Node.js/Express)

cd backend

# Set up environment
cp .env.example .env
# Edit .env with your Stellar RPC URL and contract ID

# Run development server
npm run dev

Runs on http://localhost:3001

Frontend (Next.js)

cd frontend

# Set up environment
cp .env.example .env.local
# Edit .env.local with your configuration

# Run development server
npm run dev

Visit http://localhost:3000

Run Everything Together

# From root directory
npm run dev

This starts both frontend and backend concurrently.

📚 Documentation

Comprehensive documentation is available in the documentation/ folder:

• Documentation Index - Complete documentation guide
• Project Structure - Detailed project structure
• Architecture - System design
• Guides - Step-by-step guides
• Development - Development workflows
• API Documentation - Interactive Swagger UI (when backend is running)

Quick Links

• Frontend README - Next.js setup and development
• Backend README - API server setup and endpoints
• Contributing Guidelines - How to contribute
• Refactoring Plan - Code quality improvements

🛠 Technology Stack

Smart Contracts

• Blockchain: Stellar (Soroban)
• Language: Rust
• Testing: Rust test framework

Backend API

• Runtime: Node.js 20+
• Framework: Express.js 4.18
• Language: TypeScript 5.2
• Blockchain SDK: Stellar SDK 12.0
• Security: Helmet, CORS
• Validation: Zod

Frontend

• Framework: Next.js 14 (App Router)
• Language: TypeScript 5.2
• Styling: Tailwind CSS 3.3
• State: React Query + Zustand
• Blockchain SDK: Stellar SDK 12.0
• Charts: Recharts

🎯 Features

• ✅ Create savings groups with custom rules
• ✅ Member onboarding and management
• ✅ Scheduled contributions tracking
• ✅ Transparent fund distribution
• ✅ Transaction history on-chain
• ✅ Group analytics and insights
• ✅ Wallet integration (Freighter)

🔧 Development

Prerequisites

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

Setup

# Clone repository
git clone <repo-url>
cd drips_maintener

# Install all dependencies
npm run install:all

# Set up contracts
cd contracts/ajo
cargo build

# Set up backend
cd ../../backend
cp .env.example .env
# Edit .env

# Set up frontend
cd ../frontend
cp .env.example .env.local
# Edit .env.local

Development Workflow

# From root - run everything
npm run dev

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

# Build everything
npm run build

# Run tests
npm run test:contracts  # Rust tests
npm run type-check      # TypeScript checks
npm run lint           # ESLint

📝 Environment Variables

Backend (backend/.env)

NODE_ENV=development
PORT=3001
FRONTEND_URL=http://localhost:3000
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
SOROBAN_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
SOROBAN_CONTRACT_ID=<your_contract_id>

Frontend (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

🧪 Testing

Contracts

cd contracts/ajo
cargo test

Backend

cd backend
npm run type-check
npm run lint
npm test  # (when tests are added)

Frontend

cd frontend
npm run type-check
npm run lint

All at Once

# From root
npm run type-check
npm run lint
npm run test:contracts

🚢 Deployment

Contracts

Deploy to Stellar testnet/mainnet using Stellar CLI:

cd contracts/ajo
stellar contract build
stellar contract deploy --wasm target/wasm32-unknown-unknown/release/ajo.wasm --network testnet

Backend

Deploy to Railway, Render, Heroku, or any Node.js hosting:

cd backend
npm run build
npm start

Recommended platforms:

• Railway (easiest)
• Render
• DigitalOcean App Platform
• Heroku
• AWS/GCP/Azure

Frontend

Deploy to Vercel (recommended for Next.js):

cd frontend
npm run build
npm start

Or one-click deploy:

• Vercel (recommended)
• Netlify
• Cloudflare Pages

Environment Variables

Remember to set all required environment variables in your hosting platform.

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 License

See LICENSE file.

🔗 Resources

• Stellar Documentation
• Soroban Docs
• Next.js Documentation

📧 Support

For questions and support, please open an issue on GitHub.