⚙️ ecotask-backend

The EcoTask API server — proof verification, task management, and Stellar oracle.

A Node.js/Express backend that bridges the real world and the blockchain — processing proof submissions, coordinating validators, and triggering on-chain rewards.

🌍 Overview

ecotask-backend is the off-chain infrastructure layer of EcoTask. It acts as the trusted bridge between user actions in the mobile app and the Stellar smart contracts that release rewards.

The backend is responsible for:

🗂️ Task management — Creating, listing, and expiring tasks
📸 Proof intake — Receiving photo + GPS submissions from the mobile app
🔍 Verification coordination — Routing proofs to community validators or automated checks
⛓️ Stellar oracle — Submitting verified results to the reward-engine smart contract
📊 Analytics — Tracking impact metrics (trees planted, plastic collected, CO₂ offset)
🔔 Notifications — Alerting users when their proof is verified and reward is sent

✨ Key Responsibilities

Module	What It Does
🗂️ Task API	CRUD for tasks; filter by location, type, reward, status
📤 Proof API	Accept photo uploads, extract GPS metadata, pin to IPFS
🔍 Verification Engine	Queue-based system routing proofs to validators
⛓️ Stellar Oracle	Signs and submits reward transactions to Soroban contracts
👤 User API	Profile, wallet linking, impact history
📊 Analytics API	Aggregated platform & user impact statistics
🔐 Auth	JWT-based auth with Stellar wallet signature verification

🏗️ Tech Stack

Layer	Technology	Why
Runtime	Node.js 20	Fast, async-first, huge ecosystem
Framework	Express 4	Lightweight, flexible REST APIs
Database	PostgreSQL 15	Reliable relational data for tasks & users
ORM	Prisma	Type-safe DB queries with easy migrations
Queue	BullMQ + Redis	Async proof verification job queue
File Storage	IPFS (via Web3.Storage)	Decentralised, permanent proof storage
Blockchain	Stellar SDK (JS)	Submit transactions to reward-engine contract
Auth	JWT + Stellar keypair	Wallet-based authentication
Validation	Zod	Runtime schema validation
Testing	Jest + Supertest	Unit & integration tests
Docs	Swagger / OpenAPI	Auto-generated API documentation

📁 Folder Structure

ecotask-backend/
├── src/
│   ├── routes/                   # Express route definitions
│   │   ├── tasks.ts                  # GET/POST /tasks
│   │   ├── proofs.ts                 # POST /proofs
│   │   ├── users.ts                  # GET/PUT /users
│   │   ├── auth.ts                   # POST /auth/login, /auth/verify
│   │   ├── notifications.ts          # GET /notifications
│   │   └── analytics.ts              # GET /analytics
│   │
│   ├── controllers/              # Route handler logic
│   │   ├── taskController.ts
│   │   ├── proofController.ts
│   │   ├── userController.ts
│   │   ├── authController.ts
│   │   └── analyticsController.ts
│   │
│   ├── services/                 # Core business logic
│   │   ├── verificationService.ts    # Proof review & scoring
│   │   ├── stellarService.ts         # Stellar SDK + oracle calls
│   │   ├── ipfsService.ts            # Upload proofs to IPFS
│   │   ├── notificationService.ts    # Push notification dispatch
│   │   └── geoService.ts             # Location validation & distance
│   │
│   ├── middleware/               # Express middleware
│   │   ├── auth.ts                   # JWT verification
│   │   ├── rateLimit.ts              # Request throttling
│   │   ├── upload.ts                 # Multer file upload config
│   │   └── errorHandler.ts           # Global error handling
│   │
│   ├── models/                   # Prisma schema types & helpers
│   │   ├── task.ts
│   │   ├── proof.ts
│   │   └── user.ts
│   │
│   ├── workers/                  # BullMQ background jobs
│   │   ├── verificationWorker.ts     # Process proof verification queue
│   │   └── rewardWorker.ts           # Trigger Stellar reward payouts
│   │
│   ├── utils/                    # Shared helpers
│   │   ├── logger.ts                 # Structured logging
│   │   ├── stellarUtils.ts           # Key formatting & signing helpers
│   │   └── ipfsUtils.ts              # CID formatting & gateway URLs
│   │
│   └── app.ts                    # Express app setup
│
├── prisma/
│   ├── schema.prisma             # Database schema
│   └── migrations/               # DB migration history
│
├── tests/
│   ├── routes/                   # Route integration tests
│   └── services/                 # Service unit tests
│
├── config/
│   ├── default.ts                # Default config values
│   └── production.ts             # Production overrides
│
├── .env.example
├── Dockerfile
├── docker-compose.yml
└── package.json

🚀 Getting Started

Prerequisites

Node.js >= 20
PostgreSQL 15
Redis (for BullMQ job queue)
A Stellar testnet account (funded via Friendbot)

Installation

# 1. Clone the repo
git clone https://github.com/ecotask-network/ecotask-backend.git
cd ecotask-backend

# 2. Install dependencies
npm install

# 3. Set up environment variables
cp .env.example .env
# Fill in your database URL, Stellar keys, IPFS token, etc.

# 4. Run database migrations
npx prisma migrate dev

# 5. Seed the database with sample tasks
npm run db:seed

# 6. Start the development server
npm run dev

Or with Docker (infrastructure only)

docker-compose.yml runs just the supporting services — PostgreSQL and Redis. The API itself runs on your host:

# 1. Start Postgres and Redis in the background
docker-compose up -d

# 2. Install, configure, migrate and run the API
npm install
cp .env.example .env     # fill in DATABASE_URL, JWT_SECRET, Stellar keys, etc.
npx prisma migrate dev
npm run dev
# API available at http://localhost:3000

Environment Variables

# Server
PORT=3000
NODE_ENV=development
CORS_ORIGIN=*

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/ecotask

# Redis
REDIS_URL=redis://localhost:6379

# Background jobs
EXPIRY_SWEEP_INTERVAL_MS=900000

# Stellar
STELLAR_NETWORK=testnet
STELLAR_ORACLE_SECRET_KEY=YOUR_ORACLE_SECRET_KEY
REWARD_ENGINE_CONTRACT_ID=YOUR_CONTRACT_ID

# IPFS
WEB3_STORAGE_TOKEN=YOUR_WEB3_STORAGE_TOKEN

# Auth
JWT_SECRET=your_jwt_secret_here
JWT_EXPIRES_IN=7d

📡 API Overview

The endpoint reference below is the authoritative API documentation for the current version. The API is versionless for now; once stable, breaking changes will be gated behind /v1 and /v2 prefixes.

Tasks

GET    /api/tasks              # List tasks (filter by type, location, status, reward)
GET    /api/tasks/:id          # Get single task details
POST   /api/tasks              # Create a task (admin/sponsor only)
PUT    /api/tasks/:id          # Update task (admin only)
DELETE /api/tasks/:id          # Delete/expire a task
POST   /api/tasks/:id/claim    # Claim a task (24h claim window)
DELETE /api/tasks/:id/claim    # Release a claim
GET    /api/tasks/:id/claims   # List active claims for a task

Tasks accept an optional maxCompletions capacity; once that many proofs are approved the task is auto-marked COMPLETED. Overdue ACTIVE tasks are flipped to EXPIRED by a background sweeper (EXPIRY_SWEEP_INTERVAL_MS).

Proofs

POST   /api/proofs             # Submit proof (photo + GPS + task_id)
GET    /api/proofs/:id         # Get proof status
GET    /api/proofs/user/:id    # Get all proofs by a user
GET    /api/proofs/review      # List pending proofs for manual review (admin)
POST   /api/proofs/:id/review  # Approve/reject an inconclusive proof (admin)

Proofs that the auto-verifier cannot decide are left for an admin to review via POST /api/proofs/:id/review, which resolves the verdict, notifies the user, and enqueues the reward payout when approved.

Users

POST   /api/auth/login         # Authenticate with Stellar wallet signature
GET    /api/users/:id          # Get user profile & stats
PUT    /api/users/:id          # Update profile
GET    /api/users/:id/impact   # Get impact history (trees, plastic, CO₂)

Notifications

GET    /api/notifications             # Paginated inbox for the logged-in user
GET    /api/notifications/unread-count
POST   /api/notifications/:id/read    # Mark one notification as read
POST   /api/notifications/read-all    # Mark all as read

Analytics

GET    /api/analytics/platform   # Global platform impact stats
GET    /api/analytics/trends     # Daily approved proofs & rewards series
GET    /api/leaderboard          # Top contributors (proofs + total reward)

Audit (admin)

GET    /api/audit                # Query audit logs (user, resource, paginated)

🔍 Verification Flow

User submits proof
       │
       ▼
Proof saved to DB (status: pending)
       │
       ▼
Photo + GPS pinned to IPFS
       │
       ▼
Job added to BullMQ verification queue
       │
       ▼
verificationWorker picks up job
       │
       ├── Auto-checks (GPS in task zone? Photo contains relevant content?)
       │
       └── Community validator review (if auto-check inconclusive)
              │
              ▼
        Proof approved / rejected
              │
       ┌──────┴──────┐
       ▼             ▼
   Rejected       Approved
   (notify)          │
                     ▼
            rewardWorker triggers
            Stellar oracle call
                     │
                     ▼
            ECO tokens / USDC sent
            to user's Stellar wallet
                     │
                     ▼
            User notified ✅

Admin review: proofs the auto-checks can't resolve are exposed via GET /api/proofs/review and resolved with POST /api/proofs/:id/review, which re-enters the flow at "Proof approved / rejected".

🧪 Testing

# Run all tests
npm test

# Run with coverage report
npm run test:coverage

# Run integration tests only
npm run test:integration

🗺️ Roadmap

Where the project is today and where it's headed. Priorities may shift based on contributor and community feedback — see the discussions and issues for the lively plan.

Shipped (v0.1)

Stellar wallet-based auth (challenge → signature → JWT)
Task CRUD, geo-bounded listing, claims, capacity limits (maxCompletions), and automatic expiry
Proof intake: photo upload, EXIF GPS extraction, IPFS pinning
Verification pipeline: auto-checks (GPS radius, photos, task expiry) with confidence scoring, plus admin review for inconclusive proofs
Reward payouts via the Stellar SDK (mock mode for local dev)
DB-backed notification inbox with read/unread tracking
Platform analytics, daily trends, and a rewards-enriched leaderboard
Audit logging of mutating admin/API actions

In progress

Notification delivery to end users — the inbox is persisted; push/email/webhook dispatch is the next step
Integrating the reward-engine Soroban contract (the oracle secret and contract ID are configured, but payouts currently use a direct payment op)
Real photo analysis to replace the placeholder photo_quality check

Planned

Community validator program: reviewer reputation, quorum voting, and fair review assignment
Per-user rate limits and abuse controls beyond the current global limiters
API versioning, pagination hypermedia, and generated OpenAPI docs
Impact reporting standardization (trees, plastic, CO₂) with exportable verifiable claims

🤝 Contributing

Backend developers, DevOps engineers, and database architects especially welcome! See CONTRIBUTING.md to get started.

💬 Contact & Community

Questions, ideas, or feedback? Reach the team and fellow contributors here:

Channel	What it's for
GitHub Discussions	General questions, feature ideas, project chat
GitHub Issues	Bug reports and trackable feature requests
EcoTask docs hub	Project-wide documentation and announcements

Please follow our Code of Conduct in all interactions. Security issues should be reported privately — see SECURITY.md.

📄 License

MIT — see LICENSE for details.

Ecosystem

This is part of the EcoTask Network:

Repo	Description
EcoTask-app	Mobile dApp
EcoTask-backend	Node.js API & verification engine
EcoTask-contracts	Stellar Soroban smart contracts
EcoTask-docs	Documentation hub

Part of the EcoTask Network — Because the environment deserves an economy.

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.github		.github
.husky		.husky
prisma		prisma
src		src
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.lintstagedrc.json		.lintstagedrc.json
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Uh oh!

Repository files navigation

⚙️ ecotask-backend

🌍 Overview

✨ Key Responsibilities

🏗️ Tech Stack

📁 Folder Structure

🚀 Getting Started

Prerequisites

Installation

Or with Docker (infrastructure only)

Environment Variables

📡 API Overview

Tasks

Proofs

Users

Notifications

Analytics

Audit (admin)

🔍 Verification Flow

🧪 Testing

🗺️ Roadmap

Shipped (v0.1)

In progress

Planned

🤝 Contributing

💬 Contact & Community

📄 License

Ecosystem

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

⚙️ ecotask-backend

🌍 Overview

✨ Key Responsibilities

🏗️ Tech Stack

📁 Folder Structure

🚀 Getting Started

Prerequisites

Installation

Or with Docker (infrastructure only)

Environment Variables

📡 API Overview

Tasks

Proofs

Users

Notifications

Analytics

Audit (admin)

🔍 Verification Flow

🧪 Testing

🗺️ Roadmap

Shipped (v0.1)

In progress

Planned

🤝 Contributing

💬 Contact & Community

📄 License

Ecosystem

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages