Sawabona Subsystem¶

Architecture overview and entry point for all Sawabona packages.

Package Overview¶

_SAWABONA/
├── sawabona/               Rust core — API server, CLI, payment plugins
├── sawabona-sdk-py/        Pure-Python SDK (no Rust toolchain required)
├── sawabona-sdk-rust/      Lightweight async Rust SDK (no internal crate deps)
├── sawabona-sdk-ts/        TypeScript/Node.js SDK
├── sawabona-saas/          Multi-tenant SaaS extension (FastAPI, proprietary)
├── sawabona-saas-admin-console/     Admin dashboard SPA (React + Vite, proprietary)
└── sawabona-pypi-deployer/ Private PyPI server with webhook auto-provisioning

Package Table¶

Package	Role	Language	License	Install
`sawabona`	Core platform: API server, CLI, payment plugins	Rust	BUSL-1.1 (proof kernel: Apache-2.0)	`cargo build --workspace`
`sawabona-sdk` (PyPI)	Pure-Python SDK (no Rust)	Python	Proprietary	`pip install sawabona-sdk`
`sawabona-sdk` (crates.io)	Lightweight async Rust SDK	Rust	Apache-2.0	`cargo add sawabona-sdk`
`sawabona-sdk` (npm)	TypeScript/Node.js SDK	TypeScript	Proprietary	`npm install sawabona-sdk`
`sawabona-saas`	Multi-tenant SaaS extension	Python	Proprietary	`pip install -e sawabona-saas`
`sawabona-saas-admin-console`	Admin dashboard SPA	TypeScript	Proprietary	`npm install && npm run build`
`sawabona-pypi-deployer`	Private PyPI server + webhook provisioning	Python	Apache-2.0	`pip install sawabona-pypi-deployer`

Deployment Diagram¶

┌─────────────────────────────────────────────────────────────┐
│                      End-User Application                    │
│  (imports sawabona-sdk-py / sawabona-sdk-ts / sawabona-sdk)  │
└──────────────┬──────────────────────────────────────────────┘
               │  HTTP (geometric-proof challenge flow)
               ▼
┌─────────────────────────────────────────────────────────────┐
│              sawabona (Rust API Server)                       │
│  /api/v1/geometric-proof/challenge                           │
│  /api/v1/licenses/validate                                   │
│  /api/v1/webhooks/{provider}                                 │
│  /api/v1/admin/payments/providers                            │
└──────┬──────────────────────────────────────┬───────────────┘
       │                                      │
       ▼                                      ▼
┌──────────────┐                   ┌──────────────────────────┐
│  PostgreSQL  │                   │  Payment Providers       │
│  (licenses,  │                   │  (Stripe, Paddle, …)     │
│   products,  │                   └──────────────────────────┘
│   devices)   │
└──────────────┘
       ▲
       │
┌──────────────────────────────────────────────────────────────┐
│           sawabona-saas (FastAPI, optional)                    │
│  Multi-tenant layer, OIDC SSO, audit logs, usage metering     │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│           sawabona-saas-admin-console (React SPA)                       │
│  Admin UI for tenants, licenses, products, plans, audit       │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│           sawabona-pypi-deployer                              │
│  Receives license webhooks → auto-provisions PyPI credentials │
└──────────────────────────────────────────────────────────────┘

SDK Selection Guide¶

Scenario	Recommended Package	Why
Python application	`sawabona-sdk` (Python)	Pure-Python, no Rust toolchain required — see `docs/SDKS.md`
Rust application	`sawabona-sdk` (Rust)	Lightweight, zero internal deps, async
Node.js / TypeScript application	`sawabona-sdk` (npm)	Native `node:crypto`, same API surface
Self-hosted server operator	`sawabona` (Rust core)	Full API server + CLI
Multi-tenant SaaS deployment	`sawabona-saas` + `sawabona-saas-admin-console`	Adds tenancy, OIDC, audit, billing

Getting Started¶

App developers: Pick an SDK from the table above and follow its README
SaaS deployers: See sawabona-saas/README.md and sawabona-saas-admin-console/README.md

Payment Providers — separate Cargo workspace¶

The five payment provider crates (payment-stripe, payment-flutterwave, payment-paystack, payment-paddle, payment-mollie) live under sawabona-payments/ and are workspace members. Each is wired into sawabona-api behind an opt-in cargo feature (--features stripe,paddle,… or --features all-providers); the default build registers Stripe only, so operators only pull the third-party SDKs for the providers they actually run.

Sawabona only ships a provider when its inbound-webhook authenticity can be verified with a documented, reproducible scheme. Adyen, Braintree, MercadoPago and PagSeguro were intentionally not shipped — their onboarding is sales-/ID-gated and/or their webhook schemes could not be proven from public docs (shipping unverifiable signature code would be false-green).

Environment Variables¶

See Environment variables for a consolidated reference of all env var prefixes and conventions across packages.