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.