Ystack

Services and responsibilities

Auth / Identity (Keycloak)

• Responsibility: Authentication, user identity, SSO, OIDC tokens.
• Data owned: Keycloak user record (sub), basic profile attributes.
• Notes: Other services store keycloak_id as foreign reference only.

Customer Service (customer profile / account)

• Responsibility: canonical customer profile (name, emails, billing address, company, contact info), payment-customer mapping (e.g., providerCustomerId), invoice delivery preferences, links to internal user records.
• Data owned: customer table (customer_id, keycloak_id, contact info, provider customer id, metadata).
• API examples: GET/PUT customer, attach payment method token, list customer’s subscriptions/orders.
• When to call: read-heavy for CRM and billing, write when profile changes.

Product / Plan (Catalog) Service

• Responsibility: define and manage plans, price points, features, trial configuration, promotions/coupons, entitlements (features JSON).
• Data owned: plans, SKUs, pricing tiers, feature flags, metadata.
• Notes: Admin interfaces to create/retire plans; this is authoritative for what users can buy.

Order / Checkout Service

• Responsibility: orchestrate purchase flows and create “orders” as transient/immutable records that represent a purchase attempt. Validate requested plan, pricing, coupons, compute totals and taxes, create provider checkout session or payment intent.
• Data owned: orders (order_id, customer_id, plan_id, price_at_purchase, status: created/processing/succeeded/failed/expired, idempotency key).
• Notes: Produces events (OrderCreated, OrderSucceeded, OrderFailed) consumed by Billing/Subscription and Customer services. Should be idempotent (use idempotency key).

Subscription / Billing Service

• Responsibility: map orders into subscriptions, maintain subscription lifecycle (trialing, active, past_due, canceled), reconcile provider subscription state with local state, schedule renewals and billing windows, track current_period_start/end, cancel_at_period_end flags.
• Data owned: subscriptions table, subscription status history, subscription invoices (link to invoices table).
• Notes: Acts on provider webhooks and Order events to create/update local subscription rows.

Payment Gateway Adapter

• Responsibility: encapsulate provider SDKs (Stripe, Paddle, etc.), create customers, payment methods, checkout sessions, subscriptions, invoices; normalize webhook payloads and verify signatures.
• Data owned: none (keeps provider ids for mapping).
• Notes: Keep this pluggable; return normalized result objects and propagate provider ids back to Order/Billing/Customer services.

Invoice & Payments Service (or module inside Billing)

• Responsibility: store invoices and payments, record payment attempts, refunds, reconciliation with provider invoices, retention of raw payloads for audits.
• Data owned: invoices, payments, receipts.
• Notes: Expose APIs to query invoices and download receipts.

Usage / Metering Service (optional, for metered billing)

• Responsibility: record per-feature usage (tokens, API calls), aggregate usage for billing periods, report usage to provider or generate usage-based invoices.
• Data owned: usage_records, aggregates.
• Notes: Support batching and idempotency (external_id) to avoid double-counting.