CoopLumen

Decentralized community finance on the Stellar blockchain — open source, contributor-first.

---

Why CoopLumen?

Traditional finance excludes billions of people through geographic barriers, credit requirements, and prohibitive fees. CoopLumen uses the Stellar network — with its 5-second finality, near-zero fees, and built-in DEX — to give any group (NGO, cooperative, local community, diaspora network) the tools to issue community tokens, run peer-to-peer lending pools, and govern shared treasuries without a bank in the middle.

Why Stellar specifically?

• Speed & cost: Transactions settle in 3–5 seconds for fractions of a cent
• Built-in asset primitives: Native support for custom assets, trustlines, and multi-sig
• Soroban smart contracts: Path to on-chain governance in Phase 3
• Freighter wallet: Mature browser extension for end-user signing

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Browser / PWA                         │
│   Next.js 14 (App Router)  ·  Freighter Wallet Extension    │
└───────────────────────────┬─────────────────────────────────┘
                            │ REST (JSON)
┌───────────────────────────▼─────────────────────────────────┐
│              Node.js / Express API  (port 4000)              │
│   /api/communities   /api/tokens   /api/balances             │
│                                                              │
│   ┌──────────────────┐   ┌──────────────────────────────┐   │
│   │  /contracts      │   │  PostgreSQL (off-chain meta) │   │
│   │  assets.ts       │   │  communities · members       │   │
│   │  trustlines.ts   │   │  loans                       │   │
│   │  transactions.ts │   └──────────────────────────────┘   │
│   └────────┬─────────┘                                       │
└────────────┼────────────────────────────────────────────────┘
             │ Stellar SDK (Horizon REST)
┌────────────▼────────────────────────────────────────────────┐
│              Stellar Network (Testnet / Mainnet)              │
│        Horizon API · Asset issuance · Trustlines             │
└─────────────────────────────────────────────────────────────┘

---

Project Structure

cooplumen/
├── backend/                    # Node.js / Express API
│   ├── scripts/                # Manual testnet verification scripts
│   ├── src/
│   │   ├── api/
│   │   │   ├── middleware/     # Auth, CSRF, validation, rate limiting, errors
│   │   │   ├── routes/         # One router per resource
│   │   │   ├── schemas/        # Zod request schemas
│   │   │   └── utils/          # Session tokens, cookies, pagination, Horizon errors
│   │   ├── cache/              # Redis and in-process caches
│   │   ├── contracts/          # Stellar SDK layer: assets, trustlines, payments
│   │   ├── services/           # Non-Stellar integrations (market price feed)
│   │   ├── db/                 # PostgreSQL pool, migrations and seed data
│   │   ├── testing/            # Shared test setup, teardown and fixtures
│   │   └── utils/              # Logger
│   ├── Dockerfile
│   └── package.json
├── frontend/                   # Next.js (App Router)
│   ├── e2e/                    # Playwright end-to-end suite and its support code
│   ├── src/
│   │   ├── app/                # Routes, layout, global CSS
│   │   ├── components/
│   │   │   ├── ui/             # Design-system primitives
│   │   │   ├── layout/         # Header, footer, sidebar, navigation, theme and locale
│   │   │   ├── auth/           # Protected routes and re-authentication
│   │   │   ├── community/      # Community and member forms and lists
│   │   │   ├── dashboard/      # Dashboard view
│   │   │   ├── landing/        # Marketing landing page
│   │   │   ├── loans/          # Lending flow
│   │   │   ├── multisig/       # Multi-signature proposals
│   │   │   ├── profile/        # Account profile
│   │   │   ├── reputation/     # Borrower reputation
│   │   │   ├── tokens/         # Token issuance, transfer and listing
│   │   │   ├── transactions/   # Transaction history and live feed
│   │   │   ├── treasury/       # Treasury balances and signers
│   │   │   └── wallet/         # Wallet connection and balances
│   │   ├── hooks/              # SWR data-fetching and mutation hooks
│   │   └── lib/                # API client, SWR config, schemas, design tokens
│   ├── Dockerfile
│   └── package.json
├── contracts/governance/       # Soroban governance contract (Rust)
├── deploy/                     # nginx config for blue/green production deploys
├── docs/                       # Guides, design and the OpenAPI spec
├── scripts/
│   ├── ci/                     # Branch protection setup
│   ├── db/                     # Backup and constraint-validation scripts
│   ├── deploy/                 # Deploy, rollback, smoke-test and notify scripts
│   └── issues/                 # Backlog tooling
├── .github/                    # CI, release, publish and deploy workflows
└── docker-compose*.yml         # Local, test, E2E and production stacks

---

Quick Start

Prerequisites

• Docker Desktop (v24+)
• Node.js 20+ (for local development without Docker)
• Freighter wallet browser extension

1. Clone

git clone https://github.com/BigNathan1/CoopLumen.git
cd cooplumen

2. Configure environment

# Backend
cp backend/.env.example backend/.env

# Frontend
cp frontend/.env.example frontend/.env.local

Edit backend/.env to set your Stellar keys and network preference.

3. Start with Docker (recommended)

docker compose up

This starts:

• PostgreSQL on localhost:5432
• Backend API on localhost:4000
• Frontend on localhost:3000

4. Run database migrations

docker compose exec backend npm run db:migrate

5. Open the app

Navigate to http://localhost:3000 and connect Freighter.

---

Local Development (without Docker)

# Terminal 1 — Backend
cd backend
npm install
npm run dev          # starts ts-node-dev on :4000

# Terminal 2 — Frontend
cd frontend
npm install
npm run dev          # starts Next.js on :3000

You will need a local PostgreSQL instance. Set DATABASE_URL in backend/.env.

---

Environment Variables

Backend (backend/.env)

Variable	Default	Description
PORT	4000	API server port
DATABASE_URL	—	PostgreSQL connection string
STELLAR_NETWORK	testnet	testnet or mainnet
STELLAR_HORIZON_URL	Testnet Horizon	Override Horizon endpoint
STELLAR_WEBHOOK_SECRET	-	HMAC secret for Stellar callbacks
KYC_WEBHOOK_SECRET	-	HMAC secret for KYC provider callbacks
FRONTEND_URL	http://localhost:3000	CORS allowed origin
LOG_LEVEL	info	winston log level

Frontend (frontend/.env.local)

Variable	Default	Description
NEXT_PUBLIC_API_URL	http://localhost:4000	Backend API base URL
NEXT_PUBLIC_STELLAR_NETWORK	TESTNET	Network shown in UI

---

API Reference

Communities

Method	Path	Description
GET	/api/communities	List all communities
GET	/api/communities/:id	Get a single community
POST	/api/communities	Register a new community
GET	/api/communities/:id/members	List community members
POST	/api/communities/:id/members	Add a member

Tokens

Method	Path	Description
POST	/api/v1/tokens/build-issue	Build an unsigned issuance transaction for the issuer's wallet to sign
POST	/api/v1/tokens/build-trustline	Build an unsigned trustline transaction for the holder's wallet to sign
POST	/api/v1/tokens/build-burn	Build an unsigned burn transaction for the holder's wallet to sign
POST	/api/v1/tokens/build-airdrop	Build one unsigned transaction paying every community member
POST	/api/v1/tokens/submit	Submit a signed transaction envelope
GET	/api/v1/tokens	List every token (operators only)

Balances

Method	Path	Description
GET	/api/balances/:publicKey	Get all balances for an account
GET	/api/balances/:publicKey/loans	Get loans for an account
GET	/api/balances/community/:id/loans	Get all loans in a community

Health

GET /health  →  { "status": "ok", "version": "0.1.0" }

---

Example: Register a community via cURL

curl -X POST http://localhost:4000/api/communities \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EcoDAO Lagos",
    "description": "Eco-finance cooperative for Lagos community",
    "issuerPublicKey": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "assetCode": "ECOLGS",
    "assetIssuer": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }'

---

Testing

# Backend
cd backend && npm test
cd backend && npm run test:coverage

# Frontend
cd frontend && npm test

# End-to-end (Playwright, needs the Docker Compose stack)
docker compose -f docker-compose.yml -f docker-compose.e2e.yml up -d --build --wait
cd frontend && npm run test:e2e

The end-to-end suite drives a browser against the whole stack. See Testing for how to run it and how to write a spec.

---

Documentation

• Product Requirements Document — goals, roadmap, user stories
• Contributing Guide — branch model, conventions, code review
• Architecture — how the frontend, API, database and Stellar fit together
• Database — schema, conventions and migrations
• API reference — OpenAPI specification for every endpoint
• Wallet authentication — challenge and verify, session tokens, RBAC and 401 handling
• Rate limiting — per-route limits and graduated slowdown
• Governance — Soroban proposals, token-weighted voting, quorum and execution
• Governance contract — contract types, functions, errors, events and deployment
• Multi-signature and batch operations — treasury signing lifecycle and batch payments
• SEP-12 KYC — provider integration, status mapping, privacy and security
• Testing — unit, component and Playwright end-to-end suites
• CI/CD — the CI jobs, quality gate, releases and deploy workflows
• Staging — the staging environment and its configuration
• Running PostgreSQL — connections, pooling, backups and production sizing
• Design — the Figma file and the screens designed in it

Community

• GitHub Discussions: github.com/BigNathan1/CoopLumen/discussions
• Discord: coming soon
• Stellar Developers: discord.gg/stellar

---

License

MIT © CoopLumen Contributors