Skip to content

Sawabona Developer Guide

Version: 2.0
Last Updated: 2026-01-28
Architecture: Single-Tenant Rust with Plugin-Based Payment Providers

This guide is for developers who want to contribute to Sawabona, develop custom payment provider plugins, or extend the core functionality.

Important: Sawabona is a Rust Application

Sawabona is a self-hosted Rust application with a single-tenant architecture. It provides:

  • REST API for license management
  • CLI for administrative tasks
  • Plugin-based payment provider system
  • Client SDKs: sawabona-sdk-rust (Rust) and sawabona-sdk-py (Python)
  • Geometric Proof cryptographic validation

Development Setup

Prerequisites

  • Rust 1.70+ (install from https://rustup.rs/)
  • PostgreSQL 12+
  • Docker (optional, for containerized development)
  • Git

Clone and Build

git clone https://github.com/theaistep/sawabona.git
cd sawabona

# Copy environment template
cp .env.example .env

# Build all crates
cargo build --all

# Run tests
cargo test --all

Database Setup

# Create development database
createdb sawabona_dev

# Set DATABASE_URL
export DATABASE_URL=postgresql://user:password@localhost/sawabona_dev

# Run migrations
cargo run --bin sawabona-cli -- db migrate

Running the Development Server

# Terminal 1: Start API server
cargo run --bin sawabona-api

# Terminal 2: Run CLI commands
cargo run --bin sawabona-cli -- license create

Project Structure

Workspace Crates

  • sawabona-core - Core licensing logic (license validation, geometric proof, feature management)
  • sawabona-api - REST API server using Actix-web
  • sawabona-cli - Command-line interface for administration
  • sawabona-payments - Payment provider plugin system

Payment Provider Crates

Each provider is a separate crate in sawabona-payments/:

  • sawabona-payment-stripe - Stripe payment provider
  • sawabona-payment-flutterwave - Flutterwave payment provider
  • sawabona-payment-paystack - PayStack payment provider
  • sawabona-payment-paddle - Paddle (Paddle Billing) payment provider
  • sawabona-payment-mollie - Mollie payment provider

Payment Provider Plugin Development

Plugin Trait

All payment providers implement the PaymentProvider trait:

pub trait PaymentProvider: Send + Sync {
    fn name(&self) -> &str;
    fn process_payment(&self, request: PaymentRequest) -> Result<PaymentResponse>;
    fn verify_webhook(&self, payload: &[u8], signature: &str) -> Result<bool>;
    fn health_check(&self) -> Result<HealthStatus>;
}

Creating a New Provider

  1. Create a new crate in sawabona-payments/
  2. Implement the PaymentProvider trait
  3. Add webhook verification using HMAC-SHA256
  4. Register in the provider registry
  5. Add tests and documentation

See sawabona-stripe/ for a complete example.

API Development

Adding New Endpoints

  1. Define request/response types in sawabona-core/src/models/
  2. Implement handler in sawabona-api/src/handlers/
  3. Register route in sawabona-api/src/main.rs
  4. Add tests in sawabona-api/tests/

Database Queries

Use SQLx for compile-time checked queries:

let license = sqlx::query_as::<_, License>(
    "SELECT * FROM licenses WHERE id = $1"
)
.bind(license_id)
.fetch_one(&pool)
.await?;

Testing

Run All Tests

cargo test --all

Run Specific Test

cargo test --package sawabona-core license_validation

Integration Tests

cargo test --test integration_tests

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make changes and add tests
  4. Run cargo fmt and cargo clippy
  5. Commit and push
  6. Create a Pull Request

Security Implementation

API Key Encryption

Payment provider API keys are encrypted at rest using AES-256-GCM:

use sawabona_core::encryption::encrypt_api_key;

let encrypted = encrypt_api_key(&api_key)?;

Webhook Verification

All webhooks are verified using HMAC-SHA256:

use sawabona_core::payments::verify_webhook_signature;

let is_valid = verify_webhook_signature(&payload, &signature, &secret)?;

Database Security

  • Use parameterized queries (SQLx)
  • Enable SSL for PostgreSQL connections
  • Use strong passwords
  • Regular backups

Need Help?

  • GitHub Issues: https://github.com/theaistep/sawabona/issues
  • Discussions: https://github.com/theaistep/sawabona/discussions
  • Documentation: https://docs.sawabona.dev