🛰️ SatWave

Platform for detection, classification and commercialization of recyclable materials

SatWave combines satellite monitoring, computer vision and marketplace to create an environmental wave — a data wave that cleans the planet and brings profit to recycling.

🌟 Features

• 🛰️ Satellite Monitoring — detection of new landfills via Sentinel-2
• 🤖 AI Waste Detection — waste classification (plastic, metal, paper, glass, etc.)
• 📍 Geo-validation — location verification and deduplication
• 📲 Webhook API — receiving photos from IoT bins and citizens (documentation)
• 💬 Telegram Bot — citizens can send waste photos directly from their phone (documentation)
• ♻️ Marketplace — connecting recyclers with sources of recyclable materials

🏗️ Architecture

The project follows Clean Architecture principles with separation into:

src/satwave/
├── core/                    # Domain logic (business rules)
│   ├── domain/             # Models, exceptions, interfaces
│   └── services/           # Business services (use cases)
├── adapters/               # Adapters to external world
│   ├── api/                # FastAPI endpoints (webhook)
│   ├── bot/                # Telegram bot
│   ├── storage/            # Database repositories
│   └── ml/                 # ML models (YOLOv8, Detectron2)
└── config/                 # Application configuration

📖 More details: Architecture Overview | ADR

Main photo processing flow

1. Webhook receives photo → POST /webhook/photo
2. Geolocation validation → coordinate verification
3. Duplicate check → has this location been analyzed?
4. ML waste analysis → waste type classification
5. Save to database → result available for Maxim

📚 Documentation

Full documentation is available in the docs/ folder:

• Documentation Overview - navigation through all documentation
• Quick Start Bot - launch Telegram bot in 5 minutes

🏗️ Architecture

• Architecture Overview
• Analysis Algorithm
• Services and Components

📡 API

• Webhook API
• REST Endpoints

🤖 Telegram Bot

• Telegram Bot Setup
• Bot Architecture

📋 ADR (Architecture Decision Records)

• ADR Index
• ADR-001: Clean Architecture
• ADR-002: Webhook vs Polling
• ADR-003: Duplicate Detection

🚢 Deployment and Development

• Docker Setup
• Development Setup
• Testing Guide

🚀 Quick Start

Requirements

• Python 3.11+
• Docker & Docker Compose (optional)

📖 Detailed instructions: Development Setup

Local Development

1. Clone repository

git clone <repo-url>
cd satwave

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

cp .env.example .env
# Edit .env according to your needs

5. Run application

python -m satwave.main

API will be available at: http://localhost:8000

Run Telegram Bot

1. Create bot via @BotFather

   • Detailed instructions: docs/bot/setup.md
   • Quick Start: QUICK_START_BOT.md

2. Add token to .env

   TELEGRAM_BOT_TOKEN=your_token_here

3. Run bot

   python -m satwave.adapters.bot.telegram_bot
   # or
   satwave-bot

Docker

# Run everything (API + Bot + DB)
docker-compose up --build

# Only API
docker-compose up api

# Only Bot
docker-compose up bot

📡 Usage

🤖 Telegram Bot (for citizens)

The easiest way — send waste photos via Telegram!

1. Find bot in Telegram (after setup)
2. Send /start
3. Send waste photo
4. Send geolocation (📍 via paperclip)
5. Get analysis result!

Details: Telegram Bot Setup | Quick Start

📡 API Endpoints (for integrations)

Health Check

GET /health

Send photo for analysis

POST /webhook/photo
Content-Type: multipart/form-data

Parameters:
- photo: image file (JPEG/PNG)
- latitude: latitude (-90 to 90)
- longitude: longitude (-180 to 180)
- skip_duplicate_check: skip duplicate check (optional, default: false)

Response:
{
  "analysis_id": "uuid",
  "status": "completed",
  "location": {"latitude": 55.7558, "longitude": 37.6173},
  "dominant_waste_type": "plastic",
  "detections_count": 3,
  "photo_url": "http://..."
}

Get analysis result

GET /webhook/analysis/{analysis_id}

Response:
{
  "analysis_id": "uuid",
  "status": "completed",
  "location": {"latitude": 55.7558, "longitude": 37.6173},
  "dominant_waste_type": "plastic",
  "detections_count": 3,
  "photo_url": "http://..."
}

🧪 Testing

# Run all tests
pytest

# With coverage
pytest --cov=satwave --cov-report=html

# Only unit tests
pytest tests/unit/

# Only integration tests
pytest tests/integration/

📖 More details: Testing Guide

🛠️ Development

Code Quality

# Linter + formatting
ruff check src/ tests/
ruff format src/ tests/

# Type checking
mypy src/

📖 More details: Development Setup

Branch Structure

• main — production (always green)
• dev — development
• feat/<scope>-<description> — new feature
• fix/<scope>-<description> — fixes

Commits

We use Conventional Commits:

feat(webhook): add endpoint for receiving photos
fix(ml): fix confidence threshold in classifier
docs(readme): update installation instructions

📖 More details: [Conventions in user_rules]

📦 Tech Stack

• Backend: Python 3.11+, FastAPI, Pydantic
• ML: YOLOv8, Detectron2, U-Net (TODO)
• Database: PostgreSQL + PostGIS (TODO)
• Storage: S3/MinIO (TODO)
• Testing: pytest, pytest-asyncio
• Quality: ruff, mypy (strict mode)
• Container: Docker, Docker Compose

🗺️ Roadmap

✅ Phase 1: Basic Architecture

• Domain models
• Webhook API
• Telegram bot
• Stub adapters
• Basic tests

🔄 Phase 2: ML Integration

• YOLOv8 integration for classification
• Image processing (preprocessing)
• Improved detections with bounding boxes

🔄 Phase 3: Database & Storage

• PostgreSQL + PostGIS for geodata
• Migrations (Alembic)
• S3/MinIO for photo storage

📚 Additional Resources

• GitHub Repository
• Documentation
• ADR (Architecture Decision Records)
• API Docs (after launch): http://localhost:8000/docs

📖 See also: Development Setup | Testing Guide

📄 License

TBD

---

🌊 SatWave — creating an environmental wave!