StellArts 🌟

Uber for Artisans — Built on Stellar

StellArts is a decentralized, location-based marketplace that connects skilled artisans with nearby clients. We combine fast discovery, trusted engagement, and secure payments powered by the Stellar blockchain to create a transparent platform for local services.

---

📑 Table of Contents

• Overview
• Core Features
• Getting Started
• Tech Stack
• Project Structure
• Smart Contracts
• Roadmap
• Contributing
• License

---

🚀 Overview

In many regions, finding reliable artisans (plumbers, electricians, carpenters) relies heavily on word-of-mouth, leading to limited visibility for workers and lack of trust for clients.

StellArts solves this by offering:

• For Clients: Easy discovery of verified artisans, transparent reviews, and secure escrow payments.
• For Artisans: Broader market access, fair compensation, and a reputation system that they own.

Our vision is to become the trusted decentralized infrastructure for the gig economy, promoting financial inclusion through Stellar's low-cost, high-speed network.

---

🛠️ Core Features

🔎 Discovery & Matching

• Geolocation-Based: Uber-like proximity matching to find the nearest available artisan.
• Rich Profiles: Verified skills, work history, and real-time availability.

💳 Secure & Efficient Payments

• Escrow Smart Contracts: Funds are locked exclusively until job completion is confirmed, eliminating fraud.
• Stellar-Powered:
  • Low Fees: Transactions cost < $0.01 (micropayment friendly).
  • Fast Settlement: Payments settle in 3-5 seconds.
  • Multi-Currency: Support for USDC and local assets.

⭐ Trust & Reputation

• Transparent Reviews: Rating system designed to be tamper-resistant.
• Owned Reputation: Future plans for on-chain reputation storage.

---

🚀 Getting Started

Follow these steps to set up the development environment.

Prerequisites

• Docker & Docker Compose (for Backend)
• Node.js 18+ (for Frontend)
• Rust & Soroban CLI (for Smart Contracts)

Backend (FastAPI)

1. Navigate to the backend directory:

   cd backend

2. Set up environment variables:

   cp env.example .env
   # Edit .env with your configuration if needed

3. Start the services:

   make up
   # Or: docker-compose up -d

   The API will be available at http://localhost:8000. Interact with the docs at http://localhost:8000/docs.

Frontend (Next.js)

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

   Open http://localhost:3000 in your browser.

Smart Contracts (Soroban)

For detailed contract development, see contracts/README.md.

cd contracts
cargo test

---

📦 Tech Stack

• Frontend: Next.js 13 (App Router), TypeScript, Tailwind CSS, Radix UI.
• Backend: FastAPI, Python 3.11, SQLAlchemy, PostgreSQL, Redis.
• Blockchain: Stellar Network, Soroban Smart Contracts (Rust).
• Infrastructure: Docker, GitHub Actions, AWS (planned).

---

📁 Project Structure

StellArts/
├── frontend/              # Next.js web application
├── backend/               # FastAPI backend & database
│   ├── app/               # Application code
│   └── alembic/           # Database migrations
├── contracts/             # Stellar Soroban smart contracts
│   ├── escrow/            # Payment holding logic
│   └── reputation/        # Review logic
└── README.md              # this file

---

🔐 Smart Contracts

We use Soroban to handle trustless logic:

• Escrow: Locks funds and handles release/refunds based on job status.
• Reputation: Stores rating hashes and scores to prevent manipulation.

See contracts/README.md for deployment and invocation guides.

---

💡 Roadmap

Phase 1: MVP (Current) ✅

• User auth & Artisan profiles
• Location-based search & Booking
• Stellar payment integration (Testnet)
• Basic Review system

Phase 2: Smart Contract Hardening 🚧

• Automated payment release flows
• Dispute resolution mechanism (Arbitration)
• Multi-sig wallet support

Phase 3: Enhanced Platform 🔜

• On-chain reputation data
• In-app chat & Push notifications
• Mobile Apps (iOS/Android)

---

🤝 Contributing

We welcome contributions!

1. Fork the repo and Clone it.
2. Create a Feature Branch (git checkout -b feature/cool-feature).
3. Commit your changes.
4. Test your code:
   • Backend: make test (inside /backend)
   • Frontend: npm test (inside /frontend)
   • Contracts: cargo test (inside /contracts)
5. Push and open a Pull Request.

Please read our Code of Conduct first.

---

📄 License & Contact

This project is licensed under the MIT License.

• Issues: GitHub Issues

Made with ❤️ by the StellArts Team