# smartguycodes/smart-billing architecture

> Architecture diagram of the GitHub repository smartguycodes/smart-billing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smartguycodes/smart-billing
- Repository: https://github.com/smartguycodes/smart-billing

## Overview

Smart Billing is a Laravel billing package for plan subscriptions and payments, centered on M-Pesa. Its main flow is a billable customer initiating a charge or subscription through the API or Billable trait; payment services dispatch to a driver, persist transaction state, and process gateway callbacks. Separate admin, invoice, renewal, reminder, and dunning capabilities are also represented. Source excerpts establish the payment and subscription call paths; other subsystem links are included only where README or indexed references support them.

Main entry points: [`src/Services/PaymentService.php`](https://github.com/smartguycodes/smart-billing/blob/main/src/Services/PaymentService.php) (Payment service), [`src/Models/BillingSubscription.php`](https://github.com/smartguycodes/smart-billing/blob/main/src/Models/BillingSubscription.php) (Subscriptions), [`src/Services/SubscriptionService.php`](https://github.com/smartguycodes/smart-billing/blob/main/src/Services/SubscriptionService.php) (Subscription service), [`routes/api.php`](https://github.com/smartguycodes/smart-billing/blob/main/routes/api.php) (REST routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Billing entry points"]
  node_api_routes["REST routes<br/>[api.php]"]
  node_webhook["Webhook handler"]
  node_billable["Billable trait<br/>[Billable.php]"]
  node_subscription_api["Subscription API"]
  node_plan_api["Plan API<br/>[PlanController.php]"]
  node_payment_api["Payment API"]
end

subgraph group_core["Billing domain"]
  node_subscription_service["Subscription service"]
  node_plans[("Billing plans<br/>[BillingPlan.php]")]
  node_subscriptions[("Subscriptions")]
  node_invoices[("Invoices<br/>[BillingInvoice.php]")]
  node_transactions[("Transactions")]
  node_payment_service["Payment service<br/>[PaymentService.php]"]
  node_reference["Reference generator"]
  node_payment_result["Payment result<br/>[PaymentResult.php]"]
end

subgraph group_gateway["Payment gateway"]
  node_manager["Driver manager<br/>[BillingManager.php]"]
  node_driver_contract["Driver contract<br/>[PaymentDriver.php]"]
  node_mpesa["M-Pesa driver<br/>[MpesaDriver.php]"]
end

subgraph group_operations["Billing operations"]
  node_renewals["Renewal command"]
  node_dunning["Dunning service<br/>[DunningService.php]"]
  node_reminders["Reminder command"]
  node_reminder_notification["Renewal notification"]
end

subgraph group_admin["Admin experience"]
  node_web_routes["Admin routes<br/>[web.php]"]
  node_admin_transactions["Transaction admin"]
  node_admin_plans["Plan admin<br/>[PlanController.php]"]
  node_admin_subscriptions["Subscription admin"]
  node_admin_invoices["Invoice admin"]
  node_admin_dashboard["Admin dashboard"]
  node_admin_views["Admin views"]
end

node_customer(("Billable customer"))
node_daraja["Daraja gateway"]

node_customer -->|"calls API"| node_api_routes
node_api_routes -->|"routes payment"| node_payment_api
node_api_routes -->|"routes subscription"| node_subscription_api
node_api_routes -->|"routes plans"| node_plan_api
node_api_routes -->|"routes callbacks"| node_webhook
node_customer -->|"uses trait"| node_billable
node_billable -->|"initiates charge"| node_payment_service
node_billable -->|"requests subscription"| node_subscription_service
node_payment_api -->|"initiates payment"| node_payment_service
node_subscription_api -->|"manages subscription"| node_subscription_service
node_plan_api -->|"reads plans"| node_plans
node_plan_api -->|"subscribes customer"| node_subscription_service
node_subscription_service -->|"resolves plan"| node_plans
node_subscription_service -->|"creates subscription"| node_subscriptions
node_payment_service -->|"selects driver"| node_manager
node_payment_service -->|"generates references"| node_reference
node_payment_service -->|"records payment"| node_transactions
node_payment_service -->|"returns result"| node_payment_result
node_manager -->|"creates driver"| node_mpesa
node_mpesa -->|"implements"| node_driver_contract
node_mpesa -->|"calls Daraja"| node_daraja
node_webhook -->|"handles callback"| node_payment_service
node_payment_service -->|"marks paid"| node_invoices
node_payment_service -->|"renews linked"| node_subscriptions
node_renewals -->|"charges due"| node_payment_service
node_renewals -->|"loads due"| node_subscriptions
node_dunning -->|"retries payments"| node_payment_service
node_dunning -->|"updates status"| node_subscriptions
node_reminders -->|"selects expiring"| node_subscriptions
node_reminders -->|"sends notification"| node_reminder_notification
node_web_routes -->|"routes admin"| node_admin_transactions
node_admin_transactions -->|"queries transactions"| node_transactions
node_admin_transactions -->|"verifies or refunds"| node_payment_service
node_admin_plans -->|"manages plans"| node_plans
node_admin_subscriptions -->|"reads subscriptions"| node_subscriptions
node_admin_subscriptions -->|"changes subscription"| node_subscription_service
node_admin_invoices -->|"manages invoices"| node_invoices
node_admin_dashboard -->|"summarizes billing"| node_transactions
node_admin_dashboard -->|"summarizes billing"| node_subscriptions
node_admin_dashboard -->|"summarizes billing"| node_plans
node_admin_dashboard -->|"summarizes billing"| node_invoices
node_admin_transactions -.->|"renders views"| node_admin_views

click node_api_routes "https://github.com/smartguycodes/smart-billing/blob/main/routes/api.php"
click node_webhook "https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Api/WebhookController.php"
click node_billable "https://github.com/smartguycodes/smart-billing/blob/main/src/Concerns/Billable.php"
click node_subscription_api "https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Api/SubscriptionController.php"
click node_plan_api "https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Api/PlanController.php"
click node_payment_api "https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Api/PaymentController.php"
click node_subscription_service "https://github.com/smartguycodes/smart-billing/blob/main/src/Services/SubscriptionService.php"
click node_plans "https://github.com/smartguycodes/smart-billing/blob/main/src/Models/BillingPlan.php"
click node_subscriptions "https://github.com/smartguycodes/smart-billing/blob/main/src/Models/BillingSubscription.php"
click node_invoices "https://github.com/smartguycodes/smart-billing/blob/main/src/Models/BillingInvoice.php"
click node_transactions "https://github.com/smartguycodes/smart-billing/blob/main/src/Models/BillingTransaction.php"
click node_payment_service "https://github.com/smartguycodes/smart-billing/blob/main/src/Services/PaymentService.php"
click node_reference "https://github.com/smartguycodes/smart-billing/blob/main/src/Support/ReferenceGenerator.php"
click node_payment_result "https://github.com/smartguycodes/smart-billing/blob/main/src/Support/PaymentResult.php"
click node_manager "https://github.com/smartguycodes/smart-billing/blob/main/src/Services/BillingManager.php"
click node_driver_contract "https://github.com/smartguycodes/smart-billing/blob/main/src/Contracts/PaymentDriver.php"
click node_mpesa "https://github.com/smartguycodes/smart-billing/blob/main/src/Drivers/MpesaDriver.php"
click node_renewals "https://github.com/smartguycodes/smart-billing/blob/main/src/Console/Commands/ProcessRenewalsCommand.php"
click node_dunning "https://github.com/smartguycodes/smart-billing/blob/main/src/Services/DunningService.php"
click node_reminders "https://github.com/smartguycodes/smart-billing/blob/main/src/Console/Commands/SendRemindersCommand.php"
click node_reminder_notification "https://github.com/smartguycodes/smart-billing/blob/main/src/Notifications/RenewalReminderNotification.php"
click node_web_routes "https://github.com/smartguycodes/smart-billing/blob/main/routes/web.php"
click node_admin_transactions "https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/TransactionController.php"
click node_admin_plans "https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/PlanController.php"
click node_admin_subscriptions "https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/SubscriptionController.php"
click node_admin_invoices "https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/InvoiceController.php"
click node_admin_dashboard "https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/DashboardController.php"
click node_admin_views "https://github.com/smartguycodes/smart-billing/tree/main/resources/views/admin"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_routes,node_webhook,node_billable,node_subscription_api,node_plan_api,node_payment_api toneBlue
class node_subscription_service,node_plans,node_subscriptions,node_invoices,node_transactions,node_payment_service,node_reference,node_payment_result toneAmber
class node_manager,node_driver_contract,node_mpesa toneMint
class node_renewals,node_dunning,node_reminders,node_reminder_notification toneRose
class node_web_routes,node_admin_transactions,node_admin_plans,node_admin_subscriptions,node_admin_invoices,node_admin_dashboard,node_admin_views,node_customer,node_daraja toneIndigo
```

## Components

### Billing entry points

- [REST routes](https://github.com/smartguycodes/smart-billing/blob/main/routes/api.php): `routes/api.php`
- [Webhook handler](https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Api/WebhookController.php): `src/Http/Controllers/Api/WebhookController.php`
- [Billable trait](https://github.com/smartguycodes/smart-billing/blob/main/src/Concerns/Billable.php): `src/Concerns/Billable.php`
- [Subscription API](https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Api/SubscriptionController.php): `src/Http/Controllers/Api/SubscriptionController.php`
- [Plan API](https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Api/PlanController.php): `src/Http/Controllers/Api/PlanController.php`
- [Payment API](https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Api/PaymentController.php): `src/Http/Controllers/Api/PaymentController.php`

### Billing domain

- [Subscription service](https://github.com/smartguycodes/smart-billing/blob/main/src/Services/SubscriptionService.php): `src/Services/SubscriptionService.php`
- [Billing plans](https://github.com/smartguycodes/smart-billing/blob/main/src/Models/BillingPlan.php): `src/Models/BillingPlan.php`
- [Subscriptions](https://github.com/smartguycodes/smart-billing/blob/main/src/Models/BillingSubscription.php): `src/Models/BillingSubscription.php`
- [Invoices](https://github.com/smartguycodes/smart-billing/blob/main/src/Models/BillingInvoice.php): `src/Models/BillingInvoice.php`
- [Transactions](https://github.com/smartguycodes/smart-billing/blob/main/src/Models/BillingTransaction.php): `src/Models/BillingTransaction.php`
- [Payment service](https://github.com/smartguycodes/smart-billing/blob/main/src/Services/PaymentService.php): `src/Services/PaymentService.php`
- [Reference generator](https://github.com/smartguycodes/smart-billing/blob/main/src/Support/ReferenceGenerator.php): `src/Support/ReferenceGenerator.php`
- [Payment result](https://github.com/smartguycodes/smart-billing/blob/main/src/Support/PaymentResult.php): `src/Support/PaymentResult.php`

### Payment gateway

- [Driver manager](https://github.com/smartguycodes/smart-billing/blob/main/src/Services/BillingManager.php): `src/Services/BillingManager.php`
- [Driver contract](https://github.com/smartguycodes/smart-billing/blob/main/src/Contracts/PaymentDriver.php): `src/Contracts/PaymentDriver.php`
- [M-Pesa driver](https://github.com/smartguycodes/smart-billing/blob/main/src/Drivers/MpesaDriver.php): `src/Drivers/MpesaDriver.php`

### Billing operations

- [Renewal command](https://github.com/smartguycodes/smart-billing/blob/main/src/Console/Commands/ProcessRenewalsCommand.php): `src/Console/Commands/ProcessRenewalsCommand.php`
- [Dunning service](https://github.com/smartguycodes/smart-billing/blob/main/src/Services/DunningService.php): `src/Services/DunningService.php`
- [Reminder command](https://github.com/smartguycodes/smart-billing/blob/main/src/Console/Commands/SendRemindersCommand.php): `src/Console/Commands/SendRemindersCommand.php`
- [Renewal notification](https://github.com/smartguycodes/smart-billing/blob/main/src/Notifications/RenewalReminderNotification.php): `src/Notifications/RenewalReminderNotification.php`

### Admin experience

- [Admin routes](https://github.com/smartguycodes/smart-billing/blob/main/routes/web.php): `routes/web.php`
- [Transaction admin](https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/TransactionController.php): `src/Http/Controllers/Admin/TransactionController.php`
- [Plan admin](https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/PlanController.php): `src/Http/Controllers/Admin/PlanController.php`
- [Subscription admin](https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/SubscriptionController.php): `src/Http/Controllers/Admin/SubscriptionController.php`
- [Invoice admin](https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/InvoiceController.php): `src/Http/Controllers/Admin/InvoiceController.php`
- [Admin dashboard](https://github.com/smartguycodes/smart-billing/blob/main/src/Http/Controllers/Admin/DashboardController.php): `src/Http/Controllers/Admin/DashboardController.php`
- [Admin views](https://github.com/smartguycodes/smart-billing/tree/main/resources/views/admin): `resources/views/admin`

### Other components

- **Billable customer**
- **Daraja gateway**

## Connections

- Billable customer → REST routes: calls API (evidence: `README.md`)
- REST routes → Payment API: routes payment (evidence: `routes/api.php`)
- REST routes → Subscription API: routes subscription (evidence: `routes/api.php`)
- REST routes → Plan API: routes plans (evidence: `routes/api.php`)
- REST routes → Webhook handler: routes callbacks (evidence: `routes/api.php`)
- Billable customer → Billable trait: uses trait (evidence: `README.md`)
- Billable trait → Payment service: initiates charge (evidence: `src/Concerns/Billable.php`)
- Billable trait → Subscription service: requests subscription (evidence: `src/Concerns/Billable.php`)
- Payment API → Payment service: initiates payment (evidence: `src/Http/Controllers/Api/PaymentController.php`)
- Subscription API → Subscription service: manages subscription (evidence: `src/Http/Controllers/Api/SubscriptionController.php`)
- Plan API → Billing plans: reads plans (evidence: `src/Http/Controllers/Api/PlanController.php`)
- Plan API → Subscription service: subscribes customer (evidence: `src/Http/Controllers/Api/PlanController.php`)
- Subscription service → Billing plans: resolves plan (evidence: `src/Services/SubscriptionService.php`)
- Subscription service → Subscriptions: creates subscription (evidence: `src/Services/SubscriptionService.php`)
- Payment service → Driver manager: selects driver (evidence: `src/Services/PaymentService.php`)
- Payment service → Reference generator: generates references (evidence: `src/Services/PaymentService.php`)
- Payment service → Transactions: records payment (evidence: `src/Services/PaymentService.php`)
- Payment service → Payment result: returns result (evidence: `src/Services/PaymentService.php`)
- Driver manager → M-Pesa driver: creates driver (evidence: `src/Services/BillingManager.php`)
- M-Pesa driver → Driver contract: implements (evidence: `src/Services/BillingManager.php`)
- M-Pesa driver → Daraja gateway: calls Daraja (evidence: `README.md`)
- Webhook handler → Payment service: handles callback (evidence: `src/Http/Controllers/Api/WebhookController.php`)
- Payment service → Invoices: marks paid (evidence: `src/Services/PaymentService.php`)
- Payment service → Subscriptions: renews linked (evidence: `src/Services/PaymentService.php`)
- Renewal command → Payment service: charges due (evidence: `src/Console/Commands/ProcessRenewalsCommand.php`)
- Renewal command → Subscriptions: loads due (evidence: `src/Console/Commands/ProcessRenewalsCommand.php`)
- Dunning service → Payment service: retries payments (evidence: `src/Services/DunningService.php`)
- Dunning service → Subscriptions: updates status (evidence: `src/Services/DunningService.php`)
- Reminder command → Subscriptions: selects expiring (evidence: `src/Console/Commands/SendRemindersCommand.php`)
- Reminder command → Renewal notification: sends notification (evidence: `src/Console/Commands/SendRemindersCommand.php`)
- Admin routes → Transaction admin: routes admin (evidence: `routes/web.php`)
- Transaction admin → Transactions: queries transactions (evidence: `src/Http/Controllers/Admin/TransactionController.php`)
- Transaction admin → Payment service: verifies or refunds (evidence: `src/Http/Controllers/Admin/TransactionController.php`)
- Plan admin → Billing plans: manages plans (evidence: `src/Http/Controllers/Admin/PlanController.php`)
- Subscription admin → Subscriptions: reads subscriptions (evidence: `src/Http/Controllers/Admin/SubscriptionController.php`)
- Subscription admin → Subscription service: changes subscription (evidence: `src/Http/Controllers/Admin/SubscriptionController.php`)
- Invoice admin → Invoices: manages invoices (evidence: `src/Http/Controllers/Admin/InvoiceController.php`)
- Admin dashboard → Transactions: summarizes billing (evidence: `src/Http/Controllers/Admin/DashboardController.php`)
- Admin dashboard → Subscriptions: summarizes billing (evidence: `src/Http/Controllers/Admin/DashboardController.php`)
- Admin dashboard → Billing plans: summarizes billing (evidence: `src/Http/Controllers/Admin/DashboardController.php`)
- Admin dashboard → Invoices: summarizes billing (evidence: `src/Http/Controllers/Admin/DashboardController.php`)
- Transaction admin → Admin views: renders views
