KoloGoods

A decentralized goods-based thrift system built on Stellar/Soroban. KoloGoods enables communities to pool resources, make collective purchases, and distribute goods fairly through smart contracts and coordinated backend services.

Overview

KoloGoods is an MVP scaffold providing a minimal, well-structured starter repository with three core components:

• Contract: Soroban smart contract(s) written in Rust under contract/
• Backend: Node.js + TypeScript service for procurement, webhooks, and off-chain sync
• Frontend: Next.js application for UI and dashboard

Project Structure

KoloGoods/
├── contract/                 # Soroban smart contracts
│   └── kolo_circle/         # Main circle contract
│       ├── src/
│       │   └── lib.rs       # Contract implementation
│       ├── Cargo.toml
│       └── tests/           # Contract tests
├── backend/                  # Node.js + TypeScript backend
│   ├── src/
│   │   ├── index.ts         # Server entry point
│   │   ├── routes/          # API endpoints
│   │   ├── services/        # Business logic
│   │   ├── middleware/      # Express middleware
│   │   └── types/           # TypeScript types
│   ├── package.json
│   ├── tsconfig.json
│   └── .env.example         # Environment variables template
├── frontend/                 # Next.js frontend
│   ├── src/
│   │   ├── pages/           # Next.js pages
│   │   ├── components/      # React components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── services/        # API clients
│   │   └── types/           # TypeScript types
│   ├── package.json
│   ├── next.config.js
│   └── .env.example         # Environment variables template
├── README.md
└── LICENSE

Prerequisites

• Rust toolchain (for Soroban contract development)
• Node.js 16+ and npm or yarn
• Soroban CLI (optional, for contract deployment)
• Git for version control

Quick Start

Backend Setup

cd backend
npm install
cp .env.example .env
npm run dev

The backend server runs on http://localhost:3000 by default.

Frontend Setup

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

The frontend runs on http://localhost:3001 by default.

Contract Setup

cd contract/kolo_circle
cargo build --release
cargo test

Core Features

Smart Contract (contract/kolo_circle)

The Soroban contract implements the following functions:

• create_circle: Initialize a new goods circle with members and parameters
• join_circle: Allow users to join an existing circle
• contribute: Members contribute funds or goods to the circle
• trigger_bulk_purchase: Initiate a bulk purchase when conditions are met
• rotate_distribution: Rotate distribution rights among members
• claim_goods: Members claim their allocated goods

Backend Service

The backend provides:

• REST API for circle management and member operations
• Webhook endpoints for contract event handling
• Event watcher for monitoring on-chain activity
• Procurement workflow orchestration
• Off-chain data synchronization

Frontend Application

The frontend includes:

• Dashboard for viewing active circles
• Member management interface
• Contribution tracking
• Goods distribution visualization
• Real-time notifications

Development Workflow

Making Changes

1. Create a feature branch: git checkout -b feature/your-feature
2. Make your changes in the appropriate folder
3. Test your changes locally
4. Commit with clear messages: git commit -m "feat: add new feature"
5. Push and open a pull request

Testing

Backend tests:

cd backend
npm run test

Contract tests:

cd contract/kolo_circle
cargo test

Frontend tests:

cd frontend
npm run test

Environment Configuration

Each service requires environment variables. Copy .env.example to .env in each folder and update values:

• Backend: Database URL, Soroban RPC endpoint, API keys
• Frontend: Backend API URL, Soroban network configuration
• Contract: Network configuration, contract addresses

Deployment

Contract Deployment

Deploy to Stellar testnet or mainnet using Soroban CLI:

cd contract/kolo_circle
soroban contract deploy --network testnet

Backend Deployment

Build and deploy using your preferred platform (Docker, Heroku, AWS, etc.):

cd backend
npm run build
npm start

Frontend Deployment

Deploy to Vercel, Netlify, or your preferred hosting:

cd frontend
npm run build
npm start

Contributing

We welcome contributions. Please:

1. Open an issue to discuss major changes
2. Follow the existing code style and conventions
3. Write tests for new features
4. Submit a pull request with a clear description