SaaS & Commerce — Ecosystem Overview

Granit provides a complete SaaS & Commerce ecosystem through five interdependent modules. Together they cover the full monetization lifecycle: plans → subscriptions → usage tracking → invoicing → credit balance → payment collection, with sovereignty-first design (SEPA transfer works without any external dependency).

Architecture

graph TD
    subgraph "Granit SaaS Ecosystem"
        SUB[Granit.Subscriptions] -->|CreateInvoiceCommand| INV[Granit.Invoicing]
        MET[Granit.Metering] -->|UsageSummaryReadyEto| SUB
        INV -->|InvoiceFinalizedEto| PAY[Granit.Payments]
        PAY -->|PaymentSucceededEto| INV
        INV -->|InvoicePaidEto| SUB
        INV -->|OverpaymentDetectedEto| BAL[Granit.CustomerBalance]
        BAL -->|IInvoicePrePaymentProcessor| PAY
    end

    SCH[Granit.Scheduling] -.->|scheduled plan changes| SUB
    FEA[Granit.Features] -.->|plan-driven cascade| SUB

    style SUB fill:#4a9eff,color:#fff
    style INV fill:#ff9f43,color:#fff
    style PAY fill:#2ed573,color:#fff
    style MET fill:#a55eea,color:#fff
    style BAL fill:#ff6b81,color:#fff

Event choreography

The modules communicate exclusively via integration events (Wolverine outbox). Subscriptions never listens to Payment events directly — this is critical for credit note scenarios.

Metering ──UsageSummaryReadyEto──→ Subscriptions (billing cycle orchestrator)
                                        │
                                        ├── fixed line items (plan price)
                                        ├── usage line items (from IUsageReader)
                                        │
                                        └──CreateInvoiceCommand──→ Invoicing
                                                                      │
                                              InvoiceFinalizedEto ←───┘
                                                      │
                                                      ▼
                                            IInvoicePrePaymentProcessor
                                              (CustomerBalance deducts credit,
                                               or PassThrough if not installed)
                                                      │
                                                      ▼
                                                  Payments
                                                      │
                                        PaymentSucceededEto ───→ Invoicing (RecordPayment)
                                                                      │
                                                  InvoicePaidEto ←───┘
                                                      │
                                                      ▼
                                                Subscriptions (renews/activates)

Modules

| Module | Purpose | Phase | |--------|---------|-------| | Subscriptions | Plans, subscriptions, seats, entitlements, billing cycle orchestration | 1 | | Invoicing | Invoices, credit notes, partial payments, tax, external accounting sync | 1 | | Payments | Provider-agnostic payment processing, webhooks, refunds, disputes | 1 | | Metering | Usage event recording, watermark aggregation, quota enforcement | 1 | | Tax | Tax calculation (EU VAT, Stripe Tax), VIES validation, rate management | 2 | | Customer Balance | Per-tenant credit ledger, pre-payment deduction, promotional credits with expiration | 3 |

Each module has a .Notifications package with NotificationType<TData> definitions (15 types total: 6 Subscriptions, 4 Invoicing, 5 Payments). Email templates are Phase 2.

Supporting modules

| Module | Role in SaaS | |--------|-------------| | Scheduling | One-shot future actions (scheduled plan changes, trial expiration) | | Background Jobs | Recurring scans (trial expiration, period end, aggregation, quota checks) | | Features | Plan-driven feature cascade via Subscriptions.Features bridge | | Workflow | FSM for subscription and plan lifecycle | | Notifications | Payment reminders, trial expiration, quota alerts |

Design principles

Sovereignty first

Every payment flow has a zero-dependency option. SEPA bank transfer works without Stripe, Mollie, or any US cloud provider — critical for HDS/sovereign hosting.

Agnostic by design

Invoicing and Payments are not SaaS-specific. InvoiceLineItem.SourceType accepts Subscription, Usage, OneShot, or Credit — enabling future Granit.Commerce (e-commerce) to reuse the same billing and payment infrastructure.

Hybrid provider model

Granit is the source of truth for subscription and payment status. External providers (Stripe, Mollie) are executors with declared capabilities. A tenant can have multiple providers active simultaneously (Card → Stripe, BankTransfer → SEPA, iDEAL → Mollie).

Phase strategy

| Phase | Scope | Status | |-------|-------|--------| | 1 | Subscriptions + Invoicing + Payments (Stripe + Mollie) + Metering + Notifications | Implemented | | 2 | SEPA providers, Invoicing.Internal (PDF), Invoicing.Odoo, Tax (EU VAT + Stripe Tax), dunning, multi-currency, pricing resolver | Implemented | | 3 | Email templates, customer balance (credit ledger), Open Banking (PSD2), Granit.Commerce | Implemented |

Compliance

| Requirement | Implementation | |-------------|---------------| | GDPR | Tenant isolation, data minimization, right to erasure on billing data | | ISO 27001 | Immutable audit trails on invoices and payment transactions, 3-year retention | | PCI DSS | Hosted payment pages only — no card data in Granit | | HDS | Sovereign hosting capable — SEPA transfer has zero external dependency |