settlekit/ARCHITECTURE.md
2026-06-16 02:51:34 +03:00

349 lines
13 KiB
Markdown

# 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.**
```text
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:
```json
{
"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:
```json
{
"customerId": "cus_789",
"productId": "prod_research_api",
"entitlementType": "api_credits",
"creditsRemaining": 10000,
"status": "active"
}
```
SaaS feature entitlement:
```json
{
"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 `DeliveryAction`s into an ordered, retryable run.
```text
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:
```ts
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
```text
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.
```text
┌──────────────────────────────────────────────────────────────┐
│ 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/common`** is depended on by everything and depends on nothing.
- **Access packages** (github, discord, saas, …) depend only on `common`.
- **`@settlekit/delivery`** depends on `common` plus the access packages it
orchestrates; it is the only place that composes them.
- **`@settlekit/entitlements`** owns the universal entitlement record and access
resolution.
- **Apps** depend on packages, never the reverse. The TypeScript project
references in each `tsconfig.json` encode 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
```text
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:
```text
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
```ts
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:
```text
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:
```text
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.