13 KiB
SettleKit Architecture
This document describes the core model that powers SettleKit: the universal entitlements engine, the delivery action flow, the package dependency layering, and the data model.
1. Universal entitlements (the core idea)
This is the most important architecture decision in SettleKit.
Everything becomes an entitlement.
Payment gives entitlement.
Entitlement gives access.
Access can be GitHub, SaaS, API, file, Discord, license, package, or agent tool.
A single Entitlement record represents a customer's right to access a
resource, regardless of what kind of resource it is. The EntitlementType
discriminates the access kind, and the same status/expiry machinery applies
uniformly.
Examples
GitHub repo access:
{
"customerId": "cus_123",
"productId": "prod_ai_saas_template",
"entitlementType": "github_repo_access",
"resourceId": "github_repo_456",
"status": "active",
"expiresAt": "2026-12-31T00:00:00Z"
}
API credits:
{
"customerId": "cus_789",
"productId": "prod_research_api",
"entitlementType": "api_credits",
"creditsRemaining": 10000,
"status": "active"
}
SaaS feature entitlement:
{
"customerId": "cus_555",
"productId": "prod_saas_pro",
"entitlementType": "saas_feature",
"features": {
"ai_export": true,
"team_seats": 5,
"max_projects": 20
}
}
This one concept powers the whole product: every access check — GitHub membership, SaaS feature gate, API metering, file download, Discord role, agent-tool invocation — resolves to an entitlement lookup.
2. Delivery action flow
After a payment confirms, the delivery runner (@settlekit/delivery) turns a
product's configured DeliveryActions into an ordered, retryable run.
payment.confirmed
→ grant GitHub repo access
→ issue license key
→ assign Discord role
→ create SaaS entitlement
→ send webhook
→ email buyer
Delivery actions
A product declares what should happen on purchase. Each action is a discriminated union member:
type DeliveryAction =
| { type: "github_invite"; repoId: string; permission?: "pull" | "push" | "maintain" }
| { type: "github_team_add"; orgLogin: string; teamSlug: string }
| { type: "license_key_create"; policyId: string }
| { type: "api_key_create"; scopes: string[] }
| { type: "file_access_grant"; fileId: string }
| { type: "discord_role_add"; guildId: string; roleId: string }
| { type: "saas_entitlement_create"; features: Record<string, boolean | number | string> }
| { type: "webhook_send"; url: string }
| { type: "email_send"; template: string };
This lets one purchase trigger multiple actions.
Run lifecycle
1. payments confirms a Payment (worker reads Arc / Circle)
2. delivery builds a DeliveryPlan from the product (or bundle) actions
3. delivery-runner executes each action in order, producing a DeliveryRun
4. each successful action grants an Entitlement (the universal record)
5. failed actions are retried with backoff; status is tracked per action
6. notifications emails the buyer their delivered access
The runner is idempotent per action and records DeliveryLog entries so a
retry never double-grants. The worker app drives confirmation, execution, and
retry sweeps.
3. Package dependency layering
Packages are layered so dependencies only point downward. @settlekit/common is
the foundation; the entitlements engine and delivery runner are the core; apps
sit on top.
┌──────────────────────────────────────────────────────────────┐
│ Apps │
│ api · worker · dashboard · checkout · marketplace · admin · │
│ docs · examples │
└──────────────────────────────────────────────────────────────┘
│ depends on
▼
┌──────────────────────────────────────────────────────────────┐
│ Persistence (shared Postgres layer) │
│ @settlekit/persistence — every Postgres-backed store/repo, │
│ shared by api · worker · checkout (no per-app duplication) │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Core engine │
│ delivery ──────────────┐ │
│ entitlements │ delivery orchestrates the access │
│ │ packages and writes entitlements │
└──────────────────────────┼─────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ Access / domain packages │
│ github · discord · saas · license-keys · api-keys · │
│ file-delivery · webhooks · notifications · product-catalog · │
│ bundles · payments · agent-services · escrow · arc · circle · │
│ x402 · database │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Foundation │
│ @settlekit/common — Product, Price, Bundle, Customer, │
│ CheckoutSession, Payment, Subscription, Entitlement, │
│ EntitlementType, LicenseKey, ApiKey, DeliveryRun, │
│ WebhookEndpoint, AgentService, EscrowTask, MarketplaceListing,│
│ Money, money(), Result/ok/err/isOk/isErr, SettleKitError, │
│ generateId │
└──────────────────────────────────────────────────────────────┘
Rules:
@settlekit/commonis depended on by everything and depends on nothing.- Access packages (github, discord, saas, …) depend only on
common. @settlekit/deliverydepends oncommonplus the access packages it orchestrates; it is the only place that composes them.@settlekit/entitlementsowns the universal entitlement record and access resolution.- Apps depend on packages, never the reverse. The TypeScript project
references in each
tsconfig.jsonencode this graph.
4. Persistence & dual-backend
SettleKit runs on real PostgreSQL in production and on an in-process store with
zero external infrastructure for local dev and tests. The selection is made at
boot by the DATABASE_URL environment variable.
One shared persistence layer
Every Postgres-backed store and repository lives in @settlekit/persistence
(not inside any single app). apps/api, apps/worker, and apps/checkout all
import the same stores, so they read and write one shared database — a
payment the API records is the payment the worker confirms and delivers.
Document-projection pattern
Each table carries a jsonb metadata column. The full canonical domain entity
(from @settlekit/common) is stored under metadata.__doc, and a handful of
typed columns are projected alongside it for indexing and SQL queries. The
document is the source of truth on read, so round-trips are lossless regardless
of schema drift. The codec (packDoc / unpackDoc) lives in
@settlekit/database.
Selecting a backend
DATABASE_URL set → @settlekit/persistence Postgres stores (drizzle-orm)
DATABASE_URL unset → the in-memory stores each domain package ships
Both implement the same interface, so the route/job layer is
persistence-agnostic. Migrations live in packages/database/drizzle and are
applied with pnpm --filter @settlekit/database db:migrate. The default
organization + merchant are seeded idempotently on boot.
Payment settlement is verified on-chain
When Arc settlement is configured, confirming a payment is gated on a real
on-chain verification: the submitted transaction must have transferred at
least the invoiced USDC to the session's payTo address with the required
confirmations before the payment settles and access is granted. This holds in
both apps/api (/v1/payments/:id/confirm) and the hosted checkout. With Arc
unconfigured (local dev), the recorded confirmation count is used.
5. Data model
The domain types live in @settlekit/common; the relational schema lives in
@settlekit/database. The main objects:
Organization
User
Merchant
Customer
Product
Price
Bundle
CheckoutSession
Payment
Subscription
UsageMeter
CreditBalance
Entitlement
DeliveryAction
LicenseKey
ApiKey
GitHubInstallation
GitHubRepoAccess
DiscordRoleAccess
FileAsset
WebhookEndpoint
MarketplaceListing
AgentService
EscrowTask
PayoutWallet
RiskProfile
Core type shapes
type Product = {
id: string;
merchantId: string;
name: string;
description: string;
type: ProductType;
status: "draft" | "active" | "archived";
deliveryMode: DeliveryMode;
};
type Price = {
id: string;
productId: string;
amount: string;
currency: "USDC";
interval?: "one_time" | "monthly" | "yearly";
usageBased?: boolean;
};
Database tables
Beyond the core commerce tables (products, prices, customers, payments, subscriptions, entitlements), the access-delivery and marketplace surfaces add:
github_installations discord_connections saas_plans
github_repositories discord_guilds saas_features
github_teams discord_roles saas_seats
github_repo_access_grants discord_role_grants saas_entitlement_rules
github_access_sync_runs
bundles delivery_plans agent_services
bundle_items delivery_actions agent_service_metadata
delivery_runs agent_buyers
delivery_logs agent_usage_events
escrow_tasks marketplace_listings auth_accounts
escrow_fundings risk_profiles auth_sessions
escrow_submissions agent_reputations auth_magic_links
escrow_releases download_grants auth_password_credentials
escrow_disputes
escrow_refunds coupons invoices worker_delivery_queue
escrow_reviews refunds disputes worker_webhook_jobs
payouts coupon_redemptions
dunning_states worker_email_ledger
worker_dunning_attempts
The delivery_runs / delivery_actions / delivery_logs tables are the audit
trail for the delivery flow in section 2; the *_grants and saas_* tables are
the concrete backing for the entitlements in section 1. The coupons …
payouts tables back the post-payment commerce engines; the auth_* tables
back passwordless + password auth; the worker_* tables hold the background
worker's queues and idempotency ledgers (see @settlekit/persistence).
6. HTTP API surface
apps/api exposes /v1 resources backed by the domain packages, with a
consistent { data } / { error } envelope:
auth products prices checkout-sessions
payments customers subscriptions entitlements
license-keys api-keys bundles files
webhooks delivery-runs delivery-actions agent-services
escrow coupons invoices refunds
dunning disputes payouts
integrations/github integrations/discord saas
Payment confirmation verifies the transfer on-chain (section 4) before granting
access. The worker app — also Postgres-backed via @settlekit/persistence
when DATABASE_URL is set — consumes the same domain packages to confirm
payments on Arc, execute deliveries, sync GitHub/Discord access, sweep
subscription renewals, send transactional email, and retry webhook deliveries
against that same shared database.