# niteshdass/billing-laravel architecture

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

- Interactive diagram: https://gitdiagram.com/niteshdass/billing-laravel
- Repository: https://github.com/niteshdass/billing-laravel

## Overview

1. **System shape**
   Liberu Billing is a Laravel 12 monolith for billing, invoicing, subscriptions, and hosting service automation. The core architecture is layered: HTTP/UI entry points at the top, a service/domain layer in the middle, and Eloquent models, queues, and scheduled commands at the bottom.

2. **User-facing surfaces**
   The app exposes three major UI surfaces through Filament 5 panel providers: an **Admin panel**, an **App panel** for operational users, and a **Client panel** for customers. In addition, there are classic Blade pages, Livewire screens, and a small Vue layer for richer dashboard and search widgets.

3. **HTTP and API boundary**
   Web traffic enters through `routes/web.php`, while machine-oriented access is concentrated in `routes/api.php`. Controllers under `app/Http/Controllers` handle authentication, invoices, customers, subscriptions, payments, tickets, reports, and webhooks. The API also includes an invoice resource and auth endpoints, suggesting first-class programmatic access rather than a thin internal API.

4. **Domain and persistence layer**
   The business data is modeled with many Eloquent entities: users, teams, customers, invoices, invoice items, payments, subscriptions, products/services, hosting accounts, payment gateways, knowledge base articles, tickets, quotes, webhooks, and audit logs. The database schema shows a long-lived billing domain with multi-team support, recurring billing, and operational history tracking.

5. **Service layer as the main business boundary**
   Most business logic is pushed into `app/Services`, not controllers. Key service groups include billing, payment gateway orchestration, reconciliation, subscription automation, refund/dispute handling, invoicing, reporting, knowledge base, menus, site settings, webhook dispatching, and service provisioning. This is the main place where domain workflows are coordinated.

6. **Automation and asynchronous processing**
   Background work is a major subsystem. `app/Jobs`, `app/Console/Commands`, events, listeners, and mail classes together handle recurring billing, invoice reminders, overdue service suspension, webhook processing, audit pruning, and domain synchronization. This means the system is not purely request-driven; many billing outcomes are produced by scheduled and queued processes.

7. **External integrations**
   The repo contains explicit adapters for payment gateways, domain registrars, and hosting control panels. Control panel clients cover cPanel, Plesk, DirectAdmin, Virtualmin, Softaculous, and a Liberu-specific control panel client. Registrar clients include Enom and ResellerClub. These adapters isolate vendor-specific APIs from the rest of the billing logic.

8. **Authentication, teams, and access control**
   Identity and account management are built on Jetstream, Fortify, Sanctum, and Socialstream. The app supports two-factor auth, API tokens, social login, and team-based access. Middleware and policies enforce team scoping and role-based access, which is important because many resources are shared across teams rather than being globally visible.

9. **Admin and support tooling**
   Filament resources cover administrative CRUD for users, settings, payment plans, payment gateways, subscriptions, recurring billing, audit logs, menus, and more. Client-facing Filament pages and widgets expose profile, dashboard, invoices, and social links. This admin tooling is a separate concern from the customer portal and is where most internal operations happen.

10. **Modular extension system**
   The repo includes a module framework under `app/Modules` with a `ModuleManager`, module contracts, and at least one sample `BlogModule`. This is a clear architectural boundary: core billing logic remains in the main app, while optional features can be packaged as modules without changing the base product.

11. **Notifications, email, and document generation**
   Invoice generation and payment workflows produce emails and PDFs through dedicated mail classes, Blade email templates, and PDF views. Notifications such as new tickets also live in their own subsystem. Output channels are therefore centralized and reusable across the billing workflows.

12. **Runtime and deployment topology**
   The repository is container-first. Docker assets support a standard PHP/Nginx/FPM setup as well as Laravel Octane variants using FrankenPHP, RoadRunner, and Swoole. Supervisor configurations run the app, queue workers, Horizon-like processes, and the scheduler, so the deployment model assumes multiple cooperating processes rather than a single web server.

13. **Data import/export, reporting, and auditability**
   There is a strong reporting and compliance layer: audit logs, saved searches, reports, bulk operations, and export services. These features indicate the system is designed not just to bill, but also to provide operational visibility and traceability over customer and financial events.

Main entry points: [`app/Http/Controllers`](https://github.com/niteshdass/billing-laravel/tree/main/app/Http/Controllers) (Controllers), [`app/Services/BillingService.php`](https://github.com/niteshdass/billing-laravel/blob/main/app/Services/BillingService.php) (Billing services), [`app/Models`](https://github.com/niteshdass/billing-laravel/tree/main/app/Models) (Domain models), [`app/Services/ServiceProvisioningService.php`](https://github.com/niteshdass/billing-laravel/blob/main/app/Services/ServiceProvisioningService.php) (Provisioning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI surfaces"]
  node_filament_panels["Filament panels<br/>ui"]
  node_blade_livewire_vue["Blade/Livewire/Vue<br/>ui"]
  node_http_routes["HTTP routes<br/>boundary"]
  node_http_controllers["Controllers<br/>boundary"]
end

subgraph group_core["Core domain"]
  node_billing_services["Billing services<br/>domain service<br/>[BillingService.php]"]
  node_provisioning_services["Provisioning<br/>domain service"]
  node_reporting_services["Reporting<br/>domain service<br/>[ReportService.php]"]
  node_support_services["Support tools<br/>domain service"]
  node_models[("Domain models<br/>persistence")]
  node_migrations_seeders["Schema/seeders<br/>persistence"]
end

subgraph group_automation["Automation"]
  node_jobs_commands["Jobs & commands<br/>automation"]
  node_events_listeners_mail["Events/mail<br/>automation"]
end

subgraph group_integrations["Integrations"]
  node_payment_gateways["Payment gateways<br/>integration"]
  node_control_panels["Control panels<br/>integration"]
  node_registrars["Registrars<br/>integration"]
  node_webhooks_api["Webhooks/API<br/>integration"]
end

subgraph group_platform["Platform"]
  node_auth_teams["Auth & teams<br/>platform"]
  node_modules["Modules<br/>platform"]
  node_runtime_deploy["Runtime/deploy<br/>platform"]
end

node_http_routes -->|"dispatches to"| node_http_controllers
node_http_controllers -->|"renders"| node_filament_panels
node_http_controllers -->|"serves"| node_blade_livewire_vue
node_http_controllers -->|"orchestrates"| node_billing_services
node_http_controllers -->|"orchestrates"| node_support_services
node_billing_services -->|"reads/writes"| node_models
node_provisioning_services -->|"updates"| node_models
node_reporting_services -->|"aggregates"| node_models
node_support_services -->|"manages"| node_models
node_migrations_seeders -->|"defines"| node_models
node_billing_services -->|"uses"| node_payment_gateways
node_provisioning_services -->|"uses"| node_control_panels
node_provisioning_services -->|"uses"| node_registrars
node_billing_services -->|"triggers"| node_jobs_commands
node_jobs_commands -->|"emits/consumes"| node_events_listeners_mail
node_webhooks_api -->|"notifies"| node_events_listeners_mail
node_auth_teams -->|"protects"| node_http_controllers
node_auth_teams -->|"secures"| node_filament_panels
node_modules -->|"extends"| node_billing_services
node_modules -->|"registers"| node_http_controllers
node_runtime_deploy -->|"runs"| node_jobs_commands
node_runtime_deploy -->|"serves"| node_http_routes

click node_filament_panels "https://github.com/niteshdass/billing-laravel/tree/main/app/Providers/Filament"
click node_blade_livewire_vue "https://github.com/niteshdass/billing-laravel/tree/main/resources"
click node_http_routes "https://github.com/niteshdass/billing-laravel/tree/main/routes"
click node_http_controllers "https://github.com/niteshdass/billing-laravel/tree/main/app/Http/Controllers"
click node_billing_services "https://github.com/niteshdass/billing-laravel/blob/main/app/Services/BillingService.php"
click node_provisioning_services "https://github.com/niteshdass/billing-laravel/blob/main/app/Services/ServiceProvisioningService.php"
click node_reporting_services "https://github.com/niteshdass/billing-laravel/blob/main/app/Services/ReportService.php"
click node_support_services "https://github.com/niteshdass/billing-laravel/blob/main/app/Services/KnowledgeBaseService.php"
click node_models "https://github.com/niteshdass/billing-laravel/tree/main/app/Models"
click node_migrations_seeders "https://github.com/niteshdass/billing-laravel/tree/main/database/migrations"
click node_jobs_commands "https://github.com/niteshdass/billing-laravel/tree/main/app/Jobs"
click node_events_listeners_mail "https://github.com/niteshdass/billing-laravel/tree/main/app/Events"
click node_payment_gateways "https://github.com/niteshdass/billing-laravel/blob/main/app/Services/PaymentGatewayService.php"
click node_control_panels "https://github.com/niteshdass/billing-laravel/tree/main/app/Services/ControlPanels"
click node_registrars "https://github.com/niteshdass/billing-laravel/tree/main/app/Services/Registrars"
click node_webhooks_api "https://github.com/niteshdass/billing-laravel/tree/main/app/Http/Controllers/Api"
click node_auth_teams "https://github.com/niteshdass/billing-laravel/blob/main/app/Providers/JetstreamServiceProvider.php"
click node_modules "https://github.com/niteshdass/billing-laravel/tree/main/app/Modules"
click node_runtime_deploy "https://github.com/niteshdass/billing-laravel/tree/main/Dockerfile"

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_filament_panels,node_blade_livewire_vue,node_http_routes,node_http_controllers toneBlue
class node_billing_services,node_provisioning_services,node_reporting_services,node_support_services,node_models,node_migrations_seeders toneAmber
class node_jobs_commands,node_events_listeners_mail toneMint
class node_payment_gateways,node_control_panels,node_registrars,node_webhooks_api toneRose
class node_auth_teams,node_modules,node_runtime_deploy toneIndigo
```

## Components

### UI surfaces

User-facing panels and request entry points

- [Filament panels](https://github.com/niteshdass/billing-laravel/tree/main/app/Providers/Filament): ui · Admin, app, and client panel providers · `app/Providers/Filament`
- [Blade/Livewire/Vue](https://github.com/niteshdass/billing-laravel/tree/main/resources): ui · Classic pages plus interactive dashboard widgets · `resources`
- [HTTP routes](https://github.com/niteshdass/billing-laravel/tree/main/routes): boundary · Web and API routing entry points · `routes`
- [Controllers](https://github.com/niteshdass/billing-laravel/tree/main/app/Http/Controllers): boundary · Controllers for billing, support, customers, and API access · `app/Http/Controllers`

### Core domain

Billing workflows, services, models, and persistence

- [Billing services](https://github.com/niteshdass/billing-laravel/blob/main/app/Services/BillingService.php): domain service · Core billing, invoicing, subscriptions, and reconciliation logic · `app/Services/BillingService.php`
- [Provisioning](https://github.com/niteshdass/billing-laravel/blob/main/app/Services/ServiceProvisioningService.php): domain service · Hosting, service automation, and installation workflows · `app/Services/ServiceProvisioningService.php`
- [Reporting](https://github.com/niteshdass/billing-laravel/blob/main/app/Services/ReportService.php): domain service · Reporting, exports, audit logs, and saved searches · `app/Services/ReportService.php`
- [Support tools](https://github.com/niteshdass/billing-laravel/blob/main/app/Services/KnowledgeBaseService.php): domain service · Knowledge base, canned responses, tickets, and client contacts · `app/Services/KnowledgeBaseService.php`
- [Domain models](https://github.com/niteshdass/billing-laravel/tree/main/app/Models): persistence · Eloquent entities for customers, invoices, subscriptions, payments, teams, and support · `app/Models`
- [Schema/seeders](https://github.com/niteshdass/billing-laravel/tree/main/database/migrations): persistence · Database schema evolution and bootstrap data · `database/migrations`

### Automation

Queued, scheduled, and event-driven background work

- [Jobs & commands](https://github.com/niteshdass/billing-laravel/tree/main/app/Jobs): automation · Queued and scheduled processes for reminders, suspension, webhooks, and sync · `app/Jobs`
- [Events/mail](https://github.com/niteshdass/billing-laravel/tree/main/app/Events): automation · Domain events, listeners, notifications, and email generation · `app/Events`

### Integrations

External vendor adapters and API boundaries

- [Payment gateways](https://github.com/niteshdass/billing-laravel/blob/main/app/Services/PaymentGatewayService.php): integration · Gateway orchestration and payment processing adapters · `app/Services/PaymentGatewayService.php`
- [Control panels](https://github.com/niteshdass/billing-laravel/tree/main/app/Services/ControlPanels): integration · Hosting panel adapters for cPanel, Plesk, DirectAdmin, Virtualmin, Softaculous, and Liberu · `app/Services/ControlPanels`
- [Registrars](https://github.com/niteshdass/billing-laravel/tree/main/app/Services/Registrars): integration · Domain registrar adapters · `app/Services/Registrars`
- [Webhooks/API](https://github.com/niteshdass/billing-laravel/tree/main/app/Http/Controllers/Api): integration · Webhook endpoints and API resources for programmatic access · `app/Http/Controllers/Api`

### Platform

Auth, teams, modules, and deployment/runtime

- [Auth & teams](https://github.com/niteshdass/billing-laravel/blob/main/app/Providers/JetstreamServiceProvider.php): platform · Jetstream, Fortify, Sanctum, Socialstream, policies, and team scoping · `app/Providers/JetstreamServiceProvider.php`
- [Modules](https://github.com/niteshdass/billing-laravel/tree/main/app/Modules): platform · Optional extension system and module manager · `app/Modules`
- [Runtime/deploy](https://github.com/niteshdass/billing-laravel/tree/main/Dockerfile): platform · Docker, Octane variants, supervisor processes, and container runtime · `Dockerfile`

## Connections

- HTTP routes → Controllers: dispatches to · Web and API routes route requests into controller layer
- Controllers → Filament panels: renders · Controllers and panel providers shape the main UI surfaces
- Controllers → Blade/Livewire/Vue: serves · Classic pages and interactive client-side views
- Controllers → Billing services: orchestrates · Controllers delegate billing workflows to services
- Controllers → Support tools: orchestrates · Support and knowledge endpoints delegate to services
- Billing services → Domain models: reads/writes · Billing logic persists invoices, subscriptions, payments, and related records
- Provisioning → Domain models: updates · Provisioning and automation mutate hosting and service state
- Reporting → Domain models: aggregates · Reporting builds operational and financial views from persisted data
- Support tools → Domain models: manages · Support services manage tickets, KB, contacts, and responses
- Schema/seeders → Domain models: defines · Schema and seed data underpin the domain model
- Billing services → Payment gateways: uses · Billing hands off payments and reconciliation to gateway adapters
- Provisioning → Control panels: uses · Service provisioning talks to hosting control panels
- Provisioning → Registrars: uses · Domain and hosting automation uses registrar adapters
- Billing services → Jobs & commands: triggers · Recurring billing, reminders, and billing lifecycle jobs are scheduled or queued
- Jobs & commands → Events/mail: emits/consumes · Background workflows publish events and send mail/notifications
- Webhooks/API → Events/mail: notifies · Webhook and API activity feeds into asynchronous notifications
- Auth & teams → Controllers: protects · Middleware, policies, and auth services guard controller actions
- Auth & teams → Filament panels: secures · Panels are scoped by teams and roles
- Modules → Billing services: extends · Optional modules add features around the core billing app
- Modules → Controllers: registers · Module system can contribute routes and application behavior
- Runtime/deploy → Jobs & commands: runs · Containers and supervisors run workers, scheduler, Horizon-like processes
- Runtime/deploy → HTTP routes: serves · Deployment runtime serves the web/API entry points