GeoLedger (Stellar Donation Platform)

A full-stack blockchain donation platform built on Stellar/Soroban for transparent charitable giving.

Donations are recorded with geolocation metadata, NGOs submit impact evidence, and transaction flow is backed by smart contracts and a web application stack.

What’s in this repo

• Smart contracts (Soroban/Rust) for donation flow, NGO verification, escrow, token handling, NFTs, and evidence
• Backend API (Express + TypeScript + Prisma)
• Frontend app (Next.js 14 + TypeScript + React)
• Deployment and utility scripts

Architecture

Frontend (Next.js)
   ↓ HTTP
Backend API (Express)
   ├─ PostgreSQL (via Prisma) OR mock mode (no DATABASE_URL)
   ├─ Stellar/Soroban integration
   ├─ IPFS upload + retrieval helpers
   ├─ Auth (JWT + Google/Firebase + OTP flow)
   └─ AI assistant route (Gemini)

Repository structure

/backend        Express API + Prisma schema
/frontend       Next.js UI
/contracts      Soroban smart contracts
/infra          Docker compose and infra helpers
/scripts        Contract deployment scripts

Smart contracts

Under /contracts:

• donation_registry
• ngo_verification
• impact_escrow
• token_manager
• nft_minting
• evidence

Prerequisites

• Node.js 20+
• npm
• PostgreSQL (optional)
• Without DATABASE_URL, backend falls back to in-memory mock storage for donation/project/NGO API flows
• Rust + Stellar CLI (stellar command) for contract development/deployment
• You may also see older references to stellar-cli or soroban-cli
• Freighter wallet extension (for wallet-based flows)

Quick start (local)

1) Backend

cd backend
cp .env.example .env
npm install

# Optional if using PostgreSQL
npx prisma migrate dev

npm run dev

Backend default address: http://127.0.0.1:4000

2) Frontend

cd frontend
cp .env.example .env.local
npm install
npm run dev

Frontend default address: http://localhost:3000

Environment configuration

Use:

• backend/.env.example
• frontend/.env.example

Key backend domains:

• Database: DATABASE_URL
• Auth: JWT_SECRET, Firebase service account config
• Blockchain: Soroban + contract IDs
• Evidence/IPFS: Pinata/IPFS keys
• AI: GEMINI_API_KEY

Useful API routes

Base API prefix: /api (except root GET /health)

• GET /health → use for infra/liveness checks (includes DB connectivity probe)
• GET /api/health → use for API-layer status checks (router uptime/timestamp payload)
• POST /api/auth/google
• GET /api/donations
• POST /api/donations
• POST /api/evidence/prepare
• POST /api/evidence/confirm
• GET /api/evidence/health (evidence/IPFS integration status)
• POST /api/chat/message
• GET /api/chat/suggestions
• GET /api/chat/health (Gemini integration status)

Contracts deployment

From repo root, see deployment helpers in /scripts, including:

• deploy_contracts.sh
• deploy_phase1_testnet.sh

Development commands

Backend

cd backend
npm run dev
npm run build
npm test

Seed or import NGOs:

cd backend
npm run seed:ngos
npm run import:ngos -- --file data/indian-ngos.sample.csv --limit 3

For the full India list, download a NGO-DARPAN/NITI Aayog export locally, for example a CSV with headers like unique_id, ngo_name, state_of_registration, district, city_of_registration, field_of_work, and registration_number, then run:

cd backend
npm run import:ngos -- --file data/indian-ngos.csv --source ngo-darpan --status pending

For smaller curated files with headers like Organization, Link, and Description, use a separate source label:

cd backend
npm run import:ngos -- --file ../datset.csv --source curated-india-ngos --status pending

Preview any CSV without touching the database:

cd backend
npm run import:ngos -- --file ../datset.csv --source curated-india-ngos --dry-run

Refresh the local frontend fallback list used when the backend database is unavailable:

node scripts/generate_curated_ngos.mjs datset.csv frontend/public/data/curated-india-ngos.json

Large CSV files under backend/data/*.csv are ignored by Git. Keep real registry exports local and commit only small *.sample.csv examples.

Frontend

cd frontend
npm run dev
npm run build
npm test

Notes

• Legacy demo wallet API endpoints are retired; current wallet flow is handled through real wallet integration in the frontend donation/auth paths.
• Legacy Firebase hosting config and Firestore exports were removed from the deploy path. Firebase is still used through configured auth credentials where required.
• The root-level start.sh script exists for local startup orchestration.
• Additional docs: WORKFLOW.md, UI_INTEGRATION.md, DOCUMENTATION.md, DEPLOY.md, QUICKREF.txt.

License

MIT