Deal Bot

Automated Filecoin PDP deal creation and performance monitoring system

An intelligent automation system for creating and monitoring PDP deals on the Filecoin network. Features automated deal creation, retrieval performance testing, detailed metrics tracking, and a modern web dashboard.

Features

• Automated Deal Creation - Scheduled storage deals across multiple providers
• Performance Monitoring - Real-time metrics for deals and retrievals
• Add-ons Testing - FWSS add-ons testing and comparison with provider performance
• Analytics Dashboard - Modern React UI with charts and statistics

What does dealbot do and what does it check?

See docs/checks/README.md for more details.

Project Structure

This is a monorepo containing two separate applications:

dealbot/
├── apps/
│   ├── backend/      # NestJS API server (Port 8080)
│   │   ├── src/
│   │   │   ├── deal/                # Deal creation and management
│   │   │   ├── retrieval/           # Storage retrieval testing
│   │   │   ├── metrics-prometheus/  # Prometheus instrumentation
│   │   │   ├── jobs/                # pg-boss scheduler + workers
│   │   │   └── wallet-sdk/          # Wallet and contract operations
│   │   └── README.md     # Backend-specific documentation
│   └── web/          # React + Vite dashboard (Port 5173)
│       ├── src/
│       └── README.md     # Frontend-specific documentation

Backend docs: apps/backend/README.md
Frontend docs: apps/web/README.md

Developer Docs

• docs/environment-variables.md - Full environment variables reference
• docs/DEVELOPMENT.md - Local Kubernetes development (Kind + Kustomize)
• docs/deployment.md - Container images, Kustomize manifests, runtime topology
• docs/infra.md - Ingress, egress, persistence, secrets, observability expectations
• docs/architecture.md - System architecture, component responsibilities, and data stores
• docs/production-operations.md - Links to operational docs (infra runbook, Notion tracker)
• docs/release-process.md - Release pipeline overview
• docs/release-please-flow.md - release-please details

Quick Start

Option 1: Docker Compose (Recommended for Quick Start)

• Node.js 20+
• pnpm (package manager)
• PostgreSQL database
• Filecoin wallet with tokens (for Calibration or Mainnet)

1. Clone the Repository

git clone https://github.com/FilOzone/dealbot.git
cd dealbot

2. Install Dependencies

# Install dependencies
pnpm install

3. Set Up Environment Variables

Backend Configuration

cd apps/backend
cp .env.example .env
# Edit .env with your database credentials, wallet info, etc.

Key variables to configure:

• DATABASE_* - PostgreSQL connection details
• WALLET_ADDRESS & WALLET_PRIVATE_KEY - Your Filecoin wallet
• NETWORK - calibration or mainnet
• DEALBOT_PORT - Backend server port (default: 8080)

See docs/environment-variables.md for detailed documentation on all options.

Frontend Configuration

cd ../web
cp .env.example .env
# Update VITE_API_BASE_URL if you changed DEALBOT_PORT

Default: VITE_API_BASE_URL=http://localhost:8080

4. Run the Applications

Option 1: Run both applications from Root

pnpm start:dev

Backend runs at: http://localhost:8080 ( or at DEALBOT_PORT environment variable) Frontend runs at: http://localhost:5173

Option 2: Run both applications separately in different terminals

Open two terminal windows:

Terminal 1: Backend (API Server)

cd apps/backend
pnpm start:dev    # Development with hot-reload

Backend runs at: http://localhost:8080 API Docs (Swagger): http://localhost:8080/api

Terminal 2: Frontend (Web Dashboard)

cd apps/web
pnpm dev          # Development server

Frontend runs at: http://localhost:5173

Production Deployment

Build Both Applications

# Build
pnpm build

Run Production Builds

Option 1: Run both applications from Root

pnpm start:prod

Option 2: Run both applications separately

Open two terminal windows:

# Terminal 1: Backend (API Server)
cd apps/backend
pnpm start:prod

# Terminal 2: Frontend (preview)
cd apps/web
pnpm preview

API Documentation

Complete API documentation is available via Swagger UI:

• Production: https://dealbot.filoz.org/api
• Local: http://localhost:8080/api (when running locally)

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run formatting and linting checks
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Quality

Both backend/ and web/ use Biome for formatting and linting. Before submitting a PR, run checks in both directories:

# In backend/ or web/ directory
pnpm format        # Format code
pnpm format:check  # Check formatting (CI mode)
pnpm lint          # Lint code
pnpm lint:check    # Check linting (CI mode)
pnpm check         # Run both format and lint checks
pnpm check:ci      # Run CI checks (same as CI pipeline)

Biome is configured to handle TypeScript, React/JSX, and Tailwind CSS with project-specific rules for NestJS decorators and testing files.

Resources

• Filecoin Documentation
• Synapse SDK
• NestJS Documentation

License

Dual-licensed: MIT, Apache Software License v2 by way of the Permissive License Stack.