Sawabona Rust Project Structure

Complete File Tree

sawabona/
├── Cargo.toml                          # Workspace root configuration
├── Cargo.lock                          # Dependency lock file (auto-generated)
├── .env.example                        # Environment variables template
├── README.md                           # Project overview
├── QUICK-REFERENCE.md                  # Quick reference guide
├── PROJECT-STRUCTURE.md                # This file
│
├── sawabona-core/                      # Core library crate
│   ├── Cargo.toml                      # Core crate configuration
│   └── src/
│       ├── lib.rs                      # Library root
│       ├── error.rs                    # Error types (thiserror)
│       ├── config.rs                   # Configuration management
│       ├── logging.rs                  # Logging setup (tracing)
│       │
│       ├── crypto/                     # AES-GCM encryption, KDF, secret encode/decode
│       ├── challenge/                  # Challenge engine + config (proof protocol v1)
│       ├── key_generation/             # License-key generation + environments
│       │
│       ├── models/                     # Domain models
│       │   ├── mod.rs                  # Module exports
│       │   ├── license.rs              # License entity
│       │   ├── product.rs              # Product entity
│       │   ├── plan.rs                 # Plan entity
│       │   ├── plan_revision.rs        # Plan revision (audit)
│       │   ├── product_plan_schema.rs  # Per-product plan schema
│       │   ├── device.rs               # Device entity
│       │   ├── quota.rs                # Usage quota
│       │   ├── tenant.rs               # Tenant entity
│       │   ├── validation_log.rs       # Validation audit log
│       │   ├── webhook.rs              # Webhook event log + endpoints
│       │   └── payment_integration.rs  # Provider configs (secrets encrypted at rest)
│       │
│       ├── services/                   # Business logic services
│       │   ├── mod.rs                  # Module exports
│       │   └── payments/               # Payment provider system
│       │       ├── mod.rs              # PaymentProviderTrait + ProviderConfig
│       │       ├── factory.rs          # PaymentProviderFactory (loads + decrypts config)
│       │       ├── registry.rs         # Provider registry
│       │       └── resolver.rs         # Provider/price resolution
│       │
│       └── db/                         # Database layer
│           ├── mod.rs                  # Module exports
│           ├── connection.rs           # SQLx pool management
│           ├── migrations.rs           # Schema creation
│           └── repositories/           # Data access layer
│               ├── mod.rs              # Module exports
│               ├── product_repository.rs
│               ├── plan_repository.rs
│               ├── plan_revision_repository.rs
│               ├── product_plan_schema_repository.rs
│               ├── license_repository.rs
│               ├── device_repository.rs
│               ├── quota_repository.rs
│               ├── payment_repository.rs
│               ├── pending_license_key_repository.rs
│               ├── revoked_key_repository.rs
│               ├── session_repository.rs
│               └── webhook_repository.rs
│
├── sawabona-proof/                     # Geometric-proof kernel (no DB, no server)
│   ├── Cargo.toml                      # Compiles native and wasm32
│   └── src/
│       ├── lib.rs                      # Kernel root
│       ├── crypto/                     # HKDF, HMAC-SHA256, SHA-256
│       ├── geometry/                   # Point/Segment primitives, transforms, figures/
│       ├── targets/                    # Figure collections (sets/)
│       └── proof/                      # selection, tile, invariants (GPV), proof/verify
│
├── sawabona-proof-ffi/                 # Stable C ABI over sawabona-proof (cdylib + staticlib)
│   ├── Cargo.toml
│   ├── cbindgen.toml                   # Header regeneration config
│   ├── include/
│   │   └── sawabona_proof.h            # Canonical C header
│   ├── src/
│   │   └── lib.rs                      # extern "C" entry points + string_free
│   └── tests/
│       └── kat.rs                      # Cross-impl KAT (golden GPV vector)
│
├── sawabona-api/                       # REST API server crate
│   ├── Cargo.toml                      # API crate configuration
│   └── src/
│       ├── lib.rs                      # Library root
│       ├── main.rs                     # Server entry point
│       ├── state.rs                    # Application state
│       │
│       ├── handlers/                   # HTTP request handlers (see handlers/mod.rs)
│       │   ├── mod.rs                  # Module exports
│       │   ├── health.rs               # Health check endpoint
│       │   ├── tenants.rs              # Tenant info
│       │   ├── products.rs             # Product + plan endpoints
│       │   ├── plan_schemas.rs         # Plan schema publish / by-slug / revisions
│       │   ├── licenses.rs             # License lifecycle + validate/heartbeat/usage
│       │   ├── devices.rs              # Device endpoints
│       │   ├── geometric_proof.rs      # Challenge / prove
│       │   ├── gpv.rs                  # GPV helpers
│       │   ├── catalog.rs             # Signed catalog snapshot + public key
│       │   ├── read_tokens.rs          # Scoped read-token CRUD
│       │   ├── webhook_endpoints.rs    # Outgoing webhook endpoint CRUD
│       │   ├── webhooks.rs             # Inbound payment webhook receiver
│       │   └── payments.rs             # Payment-provider admin
│       │
│       ├── middleware/                 # HTTP middleware
│       │   ├── mod.rs                  # Module exports
│       │   ├── auth.rs                 # Authentication
│       │   ├── rate_limit.rs           # Rate limiting
│       │   ├── logging.rs              # Request logging
│       │   └── security.rs             # Security headers
│       │
│       └── routes.rs                   # Route definitions
│
├── sawabona-cli/                       # Command-line interface crate
│   ├── Cargo.toml                      # CLI crate configuration
│   └── src/
│       ├── main.rs                     # CLI entry point
│       └── commands/                   # CLI commands
│           ├── mod.rs                  # Module exports
│           ├── db.rs                   # Database commands
│           ├── server.rs               # Server commands
│           ├── license.rs              # License commands
│           └── provider.rs             # Payment provider commands
│
├── sawabona-payments/                  # Payment provider plugins (workspace members; opt-in via cargo features)
│                                       #   Default build registers Stripe only; enable others with
│                                       #   `--features paddle,flutterwave,…` or `--features all-providers`.
│   ├── payment-stripe/                 # Stripe provider
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   ├── payment-flutterwave/            # Flutterwave provider
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   ├── payment-paystack/               # PayStack provider
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   ├── payment-paddle/                 # Paddle (Paddle Billing) provider
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   └── payment-mollie/                 # Mollie provider
│       ├── Cargo.toml
│       └── src/lib.rs
│
├── templates/                          # Starter templates
│   ├── sawabona-starter-stripe/        # Stripe starter template
│   │   ├── Cargo.toml
│   │   ├── src/main.rs
│   │   └── .env.example
│   ├── sawabona-starter-flutterwave/   # Flutterwave starter template
│   └── sawabona-starter-paystack/      # PayStack starter template
│
├── docs/                               # Documentation
│   ├── index.md                        # Documentation index (the site's home page)
│   ├── REFERENCE.md                  # Comprehensive user manual
│   ├── payments.md                     # Payment provider guide
│   ├── guides/                         # User guides
│   │   ├── REFERENCE.md
│   │   ├── REFERENCE.md
│   │   ├── DEVELOPER-GUIDE.md
│   │   ├── DEPLOYMENT-GUIDE.md
│   │   └── PAYMENT-PROVIDER-INTEGRATION.md
│   ├── reference/                      # API reference
│   │   ├── API-REFERENCE.md
│   │   ├── API_DOCUMENTATION.md
│   │   ├── API-SCHEMAS.md
│   │   └── CLI-REFERENCE.md
│   ├── security/                       # Security documentation
│   │   ├── SECURITY-OVERVIEW.md
│   │   ├── GEOMETRIC-PROOF.md
│   │   ├── ENCRYPTION-AT-REST.md
│   │   └── SECRETS-MANAGEMENT-GUIDE.md
│   └── testing/                        # Testing guides
│       └── TESTING-GUIDE.md
│
└── examples/                           # Practical examples
    ├── self-hosted-deployment/         # docker-compose.yml, nginx.conf, sawabona.service, README.md
    ├── cli-usage/                      # README.md
    └── webhooks/                       # stripe-handler.rs, README.md

Integration tests live in each crate's own tests/ directory (e.g. sawabona-api/tests/, sawabona-proof-ffi/tests/), not a top-level tests/ tree. See the Testing section below.

Module Hierarchy

sawabona-core

sawabona_core
├── config            # Config, ServerConfig, DatabaseConfig, LoggingConfig, RateLimitConfig
├── error             # Error (enum), Result<T>
├── logging           # init_logging()
├── crypto            # encryption (AES-GCM), kdf, encode/decode_encrypted_secret
├── challenge         # ChallengeConfig/Parameters, challenge engine (proof protocol v1)
├── key_generation    # license-key generation + KeyEnvironment
├── models
│   ├── License
│   ├── Product
│   ├── Plan
│   ├── PlanRevision
│   ├── ProductPlanSchema
│   ├── Device
│   ├── Quota
│   ├── Tenant
│   ├── ValidationLog
│   ├── Webhook (event log + endpoints)
│   └── payment_integration (Stripe/Paddle/PayStack/Flutterwave/Mollie configs; secrets encrypted at rest)
├── services
│   └── payments      # PaymentProviderTrait, ProviderConfig, factory, registry, resolver
└── db
    ├── connection    # Database (type alias), create_pool()
    ├── migrations    # run_migrations()
    └── repositories
        ├── ProductRepository
        ├── PlanRepository
        ├── PlanRevisionRepository
        ├── ProductPlanSchemaRepository
        ├── LicenseRepository
        ├── DeviceRepository
        ├── QuotaRepository
        ├── PaymentRepository
        ├── PendingLicenseKeyRepository
        ├── RevokedKeyRepository
        ├── SessionRepository
        └── WebhookRepository

sawabona-proof / sawabona-proof-ffi

sawabona_proof                         # the single canonical proof kernel
├── crypto            # derive_key (HKDF), hmac_sha256, sha256_hex
├── geometry          # Point2D/Segment, transforms, figures/
├── targets           # FigureCollection sets, resolve_collection()
└── proof
    ├── selection     # derive_figure_index, figure_descriptor, derive_proof_key, derive_geo_params
    ├── tile          # build_tile
    ├── invariants    # compute_gpv (GeometricProofVector)
    └── proof         # compute_proof / verify_proof

sawabona_proof_ffi                     # C ABI over the kernel (re-binds, never reimplements)
├── sawabona_compute_proof()
├── sawabona_sha256_hex()
├── sawabona_hmac_sha256()
├── sawabona_proof_version()
└── sawabona_string_free()

sawabona-api

sawabona_api
├── state
│   └── AppState
├── handlers
│   ├── health_check()
│   ├── get_tenant_info()
│   ├── create_product()
│   ├── get_product()
│   ├── list_products()
│   ├── create_license()
│   ├── get_license()
│   ├── get_license_by_key()
│   ├── validate_license()
│   ├── revoke_license()
│   ├── track_license_usage()
│   ├── list_devices()
│   ├── deactivate_device()
│   ├── delete_device()
│   ├── generate_challenge()
│   ├── verify_proof()
│   ├── handle_webhook()
│   ├── list_providers()
│   ├── get_provider()
│   ├── update_provider()
│   └── test_provider_health()
├── middleware
│   ├── auth (JWT + API key)
│   ├── rate_limit
│   ├── logging
│   └── security (headers)
└── routes
    └── create_router()

sawabona-cli

sawabona_cli
├── main()                              # Clap entry — dispatches to each command module
└── commands
    ├── db          # Database subcommands (init, migrate, status, seed, reset)
    ├── server      # Run the Actix-web API server (foreground or background)
    ├── license     # Create / list / revoke / rotate licenses
    ├── product     # Create / list / update products
    ├── plan        # Create / list / update plans attached to products
    ├── config      # Show, validate, and mask the effective configuration
    ├── health      # Hit /health and /readyz against a running instance
    ├── interactive # REPL / TUI shell wrapping the other subcommands
    └── init        # Scaffold a first-run deployment: .env, admin key, seed data

The canonical list of subcommands is declared in sawabona-cli/src/commands/mod.rs — any additions there must be mirrored here to keep this document in sync.

Key Files by Purpose

Configuration

• sawabona-core/src/config.rs - Environment-based configuration
• .env.example - Configuration template

Error Handling

• sawabona-core/src/error.rs - Domain error types

Logging

• sawabona-core/src/logging.rs - Structured logging setup

Domain Models

• sawabona-core/src/models/license.rs - License entity
• sawabona-core/src/models/product.rs - Product entity
• sawabona-core/src/models/plan.rs - Plan entity
• sawabona-core/src/models/plan_revision.rs - Plan revision (audit)
• sawabona-core/src/models/product_plan_schema.rs - Per-product plan schema
• sawabona-core/src/models/tenant.rs - Tenant entity
• sawabona-core/src/models/device.rs - Device entity
• sawabona-core/src/models/quota.rs - Usage quota
• sawabona-core/src/models/validation_log.rs - Validation audit log
• sawabona-core/src/models/webhook.rs - Webhook event log + endpoints
• sawabona-core/src/models/payment_integration.rs - Provider configs (secrets encrypted at rest)

Database

• sawabona-core/src/db/connection.rs - Connection pool
• sawabona-core/src/db/migrations.rs - Schema creation
• sawabona-core/src/db/repositories/*.rs - Data access

API

• sawabona-api/src/state.rs - Shared application state
• sawabona-api/src/handlers/*.rs - HTTP endpoints
• sawabona-api/src/routes.rs - Route definitions

CLI

• sawabona-cli/src/main.rs — CLI entry point (Clap)
• sawabona-cli/src/commands/mod.rs — Subcommand module declarations
• sawabona-cli/src/commands/db.rs — Database lifecycle commands
• sawabona-cli/src/commands/server.rs — API server commands
• sawabona-cli/src/commands/license.rs — License create / list / revoke / rotate
• sawabona-cli/src/commands/product.rs — Product CRUD
• sawabona-cli/src/commands/plan.rs — Plan CRUD
• sawabona-cli/src/commands/config.rs — Config inspect / validate / mask
• sawabona-cli/src/commands/health.rs — Liveness / readiness probe runner
• sawabona-cli/src/commands/interactive.rs — Interactive REPL shell
• sawabona-cli/src/commands/init.rs — First-run bootstrap command

Dependency Graph

sawabona-cli
├── sawabona-api
│   └── sawabona-core
│       ├── tokio
│       ├── serde
│       ├── sqlx
│       ├── uuid
│       ├── chrono
│       ├── config
│       ├── dotenv
│       ├── tracing
│       ├── tracing-subscriber
│       ├── thiserror
│       └── anyhow
│
└── sawabona-core (same as above)

Build Artifacts

After cargo build:

target/
├── debug/
│   ├── sawabona (CLI binary)
│   ├── deps/
│   └── ...
└── release/
    ├── sawabona (optimized CLI binary)
    ├── deps/
    └── ...

Testing (~720 tests)

Unit Tests (inline #[cfg(test)] mod tests)

• sawabona-core/src/ — 413+ tests (models, crypto, services, config, DB repos, targets, challenge engine)
• sawabona-api/src/error.rs — 10 tests (status codes, Display, From conversion)
• sawabona-api/src/middleware/auth.rs — 13 tests (JWT validation, API key, constant-time eq)
• sawabona-api/src/middleware/rate_limit.rs — 3 tests (enabled/disabled, defaults)
• sawabona-cli/src/utils.rs — 12 tests (format_duration, format_currency, colorize_status)
• sawabona-cli/src/commands/config.rs — 4 tests (mask_connection_string)
• sawabona-payments/payment-stripe/src/provider.rs — 18 tests (wiremock: subscriptions, webhooks, health)

Integration Tests

• sawabona-api/tests/db_lifecycle_tests.rs — 5 real-DB scenarios (product→plan→license, challenge with greek/zodiac, auth enforcement)
• sawabona-api/tests/api_endpoint_tests.rs — 54 endpoint integration tests

CLI E2E Tests

• sawabona-cli/tests/cli_e2e_test.sh — 10 shell tests (version, db init/status/seed, health, config, error handling)

Python

Python apps use the sawabona-sdk-py SDK (pip install sawabona-sdk, pure-Python, no Rust toolchain) — see docs/SDKS.md.

Running Tests

cargo test --workspace                          # All Rust tests
./sawabona-cli/tests/cli_e2e_test.sh           # CLI E2E (needs PostgreSQL)