Skip to main content

Design and Architecture

The Stellar Disbursement Platform consists of four services deployed together:

  • Dashboard: the user interface administrators use to initiate and track the progress of disbursements
  • SDP Core Service: the core backend service that performs several functions:
    • Dashboard API: the API used by the front-end UI for all disbursement requests. The API is documented here
    • Admin API: the API used by the host organization to manage tenant provisioning and configuration. The API is documented here
    • Messaging Service: a recurring process that sends text messages to users prompting them to download the wallet selected for a particular disbursement and verify their phone with an OTP
    • Wallet Registration UI: a web application that collects and verifies the recipient’s OTP code and verification information via Stellar’s SEP-24: Hosted Deposit and Withdrawal protocol
  • Anchor Platform Service: the API server that the wallet uses to authenticate and initiate the recipient’s registration process through the SEP-24 deposit flow
  • Transaction Submission Service: the service that submits all payment transactions to the Stellar network. This service is designed to maximize payment throughput, handle queuing, and graceful resubmission/error handling

Dependencies​

  • Container Orchestration: the SDP is packaged as Docker containers and can be deployed to Kubernetes or AWS Fargate. SDF provides a Helm Chart for Kubernetes
  • Postgres: the SDP uses a Postgres database server for all of its services
  • Apache Kafka: the SDP optionally uses Kafka for streaming events between services. This is primarily used between SDP Core Service and Transaction Submission Service
  • Twilio or AWS SNS and SES: the SDP’s messaging service uses SMS messages via Twilio or AWS SNS and administrative emails for organization account setup and recovery via AWS SES
  • Stellar Accounts:
    • Distribution Account: the SDP requires access to at least one funded Stellar account to make payments to the recipient
    • SEP-10 Auth Account: the SDP requires a Stellar account for the mutual authentication protocol SEP-10: Stellar Web Authentication used to connect to wallet applications

Architecture Diagram​

Architecture Diagram

Database & Schemas​

The SDP uses a Postgres database for all of its services. The database schema is managed by the SDP Core Service and is versioned in the codebase. The database schema is designed to be tenant-aware, meaning that each tenant has its own set of tables and data. This allows the SDP to be multi-tenant and support multiple organizations using the same instance.

There are 3 types of schemas in the database:

  • Admin Schema: contains tables for managing tenants. This schema is used by the Admin API to manage tenant configuration and provisioning.
  • TSS Schema: contains tables for managing transactions. This schema is used by the Transaction Submission Service to manage the state of payment transactions.
  • Tenant Schemas: each tenant has its own schema that contains tables for managing disbursements, recipients, and other tenant-specific data. These schemas are prefixed with sdp_.

Multi-tenancy​

The SDP can be deployed in a multi-tenant configuration, where multiple organizations share the same instance of the SDP. Each organization is referred to as a tenant and has its own set of data and configuration. A host organization can manage multiple tenants and manage their configuration through the Admin API.

Tenant Resolution​

The SDP uses a tenant resolution strategy to determine which tenant a request belongs to. Tenant resolution is only required for unauthenticated requests, as authenticated requests include the tenant information already in the JWT token.

  • Header: the SDP-Tenant-Name header is used to specify the tenant name in the request. When present, this header is used to attempt resolving the tenant.
  • Subdomain: the SDP can use the subdomain of the request URL to resolve the tenant. For example, tenant1.sdp.backend.test would resolve to the tenant tenant1.

Resolution priority goes as follows: JWT token (authenticated requests) > Header > Subdomain.

Single Tenant Mode​

When single tenant mode is enabled using the SINGLE_TENANT_MODE environment variable, all tenants will automatically resolve to the default tenant. A default tenant is set by calling the API POST /tenants/default-tenant.

Default tenant is useful for development purposes or when the SDP is used by a single organization. This allows the organization to skip specifying the tenant in every request and simplifies the SDP setup operationally by removing the need of providing wildcard TLS certificates for multi-tenant configurations.

Subdomain Resolution​

When running the SDP in multi-tenant mode, the SDP uses the subdomain of the request URL to resolve the tenant. For example, tenant1.sdp.backend.test would resolve to the tenant tenant1. This allows the SDP to differentiate between tenants without requiring the tenant name to be specified in the request.

The subdomain resolution is particularly important for the Wallet Registration process, as the SDP relies on subdomains to differentiate between tenants during the SEP-24 deposit flow. Home domains, which contain the tenant name as a subdomain, are used during the registration process by the SDP to identify the tenant and route the wallet-registration request to the correct tenant context.