Backend

Reference for every PHP layer that ships with Modularous. Sections below are ordered alphabetically — each one points at the directory under src/ it documents and the matching reference page under system-reference/backend/.

Section	Source path	Reference
Activators	src/Activators/	Activators →
Brokers	src/Brokers/	Brokers →
Console Commands	src/Console/	Console guide →
Controllers	src/Http/Controllers/	Controllers →
Entities	src/Entities/	Entities →
Entity Traits	src/Entities/Traits/	Entity Traits →
Events & Listeners	src/Events/, src/Listeners/	Events & Listeners →
Facades	src/Facades/	Facades →
Form Requests	src/Http/Requests/	Form Requests →
Generators	src/Generators/	Generators →
Helpers	src/Helpers/	Helpers →
Middleware	src/Http/Middleware/	Middleware →
Notifications	src/Notifications/	Notifications →
Providers	src/Providers/	Providers →
Repository Traits	src/Repositories/Traits/	Repository Traits →
Scheduled Jobs	src/Schedulers/	Scheduled Jobs →
Services	src/Services/	Services →
Support	src/Support/	Support →
View Composers	src/Http/ViewComposers/	View Composers →

---

Architecture at a glance

Modularous layers a Laravel package on top of nWidart/laravel-modules and adds a CRUD-aware admin pipeline that every module inherits. The backend is organised as a stack of composable layers — bootstrap on top, persistence at the bottom — with cross-cutting services sitting alongside.

┌──────────────────────────────────────────────────────────────────┐
│  Bootstrap        Providers · Activators · Facades · Helpers     │
│                   ──────────────────────────────────────────────  │
│  HTTP entry       Middleware → Form Requests → Controllers       │
│                   ──────────────────────────────────────────────  │
│  Domain           Repositories ↔ Repository Traits               │
│                   Entities ↔ Entity Traits                       │
│                   ──────────────────────────────────────────────  │
│  Reactions        Events → Listeners → Notifications             │
│                   ──────────────────────────────────────────────  │
│  Background       Scheduled Jobs · Console Commands              │
│                   ──────────────────────────────────────────────  │
│  Cross-cutting    Services · Support · View Composers · Brokers  │
│                   Generators (build-time only)                   │
└──────────────────────────────────────────────────────────────────┘

Typical request lifecycle

A normal admin CRUD request walks through most of these layers in order:

1. Providers — ModularousProvider boots child providers (BaseServiceProvider, RouteServiceProvider, AuthServiceProvider, …) and binds every container entry the rest of the stack depends on.
2. Activators — ModularousActivator and ModuleActivator short-circuit the request if the target module or route is disabled.
3. Middleware — the web / admin / api pipelines run guards (Authenticate, Authorization, Hostable, Language, Navigation, HandleInertiaRequests, …).
4. Form Request — a BaseFormRequest subclass authorizes the user and validates input before the controller method runs.
5. Controller — BaseController resolves the active route, applies traits (ManageIndexAjax, ManageInertia, ManagePrevious, ManageSingleton, ManageTranslations), renders the form schema, and delegates persistence to $this->repository.
6. Repository (+ Traits) — the base Repository invokes every applicable repository trait (prepareFieldsBeforeSave{Trait}, afterSave{Trait}, …) around the Eloquent save().
7. Entity (+ Traits) — Eloquent models compose entity traits for slugs, positions, soft-delete, translations, media, files, repeaters, blocks, processes, state, payments, presenters, and broadcasting context.
8. Events & Listeners — model lifecycle and auth events fire; Listener::handle() resolves the matching {EventName}Notification and dispatches it when modularous.mail.enabled = true.
9. View Composers — for Inertia/Blade responses, composers inject shared props (current user, navigation, uploader configs, localization, URLs).
10. Response — Inertia/JSON/Blade payload returns to the client; broadcasted events propagate over Echo channels.

How the layers reference each other

If you are working on…	You typically touch…
A new admin route	Providers → Generators → Controllers → Form Requests → Entities → Repository Traits
Authentication / registration	Middleware → Controllers (Auth) → Brokers → Notifications → Events & Listeners
Caching / invalidation	Services (ModularousCacheService, CacheRelationshipGraph) → Repository Traits (Logic) → Console Commands (cache:*)
File / media uploads	Controllers (Filepond / FileLibrary / MediaLibrary) → Form Requests → Services (FilepondManager, FileLibrary, MediaLibrary, Uploader) → Entity Traits (HasFileponds, HasFiles, HasImages)
Multi-tenant routing	Providers (RouteServiceProvider) → Support (HostRouting) → Middleware (Hostable) → Facades (HostRouting)
Real-time / chat	Events & Listeners → Notifications → Services (BroadcastManager) → Scheduled Jobs (ChatableScheduler)

→ Architecture deep-dives also live under the system reference — cache, broadcasting, host routing, and module conventions are documented there.

---

Activators

Directory: src/Activators/ · Namespace: Unusualify\Modularous\Activators

Activators persist and resolve enable/disable state. Modularous splits activation into two layers — module-level (whether a module loads at all) and route-level (whether a specific route action inside a module is enabled).

Class	Persisted in	Purpose
ModularousActivator	modules_statuses.json + cache	Stores and resolves module-level statuses (enabled / disabled)
ModuleActivator	routes_statuses.json per module	Stores and resolves route-level statuses inside a module

CLI integration: route:disable, route:enable, route:status read and mutate these files.

→ Activators reference

---

Brokers

Directory: src/Brokers/ · Namespace: Unusualify\Modularous\Brokers

Powers the email-verification-based registration flow behind the Register facade. Mirrors Laravel's password broker design, adapted for verification tokens.

Class	Role
RegisterBroker	Executes verification-link and registration-token operations
RegisterBrokerManager	Resolves named broker instances and selects the default broker
TokenRepositoryInterface	Contract for email-based token repository methods

Flow: controller → Register::broker() → RegisterBrokerManager → RegisterBroker → TokenRepositoryInterface.

→ Brokers reference

---

Console Commands

Directory: src/Console/ · Namespace: Unusualify\Modularous\Console

Discovered via CommandDiscovery::discover() in BaseServiceProvider. Every command extends a BaseCommand, which adds module-aware option resolution and consistent output formatting on top of Illuminate\Console\Command.

Category	Path	Commands
Cache	Console/Cache/	cache:clear, cache:list, cache:warm, cache:stats, cache:versions, cache:graph
Coverage	Console/Coverage/	coverage:report, coverage:methods
Docs	Console/Docs/	Docs scaffolding helpers
Flush	Console/Flush/	flush, flush:filepond, flush:sessions
Make	Console/Make/	make:controller, make:controller-api, make:event, make:feature, make:input-hydrate, make:laravel-test, make:listener, make:migration, make:model, make:module, make:operation, make:repository, make:repository-trait, make:request, make:route, make:route-permissions, make:stubs, make:theme, make:vue-input, make:vue-test
Migration	Console/Migration/	migrate, migrate:refresh, migrate:rollback
Module	Console/Module/	module:fix, module:remove, route:disable, route:enable, route:status
Operations	Console/Operations/	Workflow / batch-operation runners
Setup	Console/Setup/	create-superadmin, create:database, install, setup:dev
Sync	Console/Sync/	sync:states, sync:translations
Top-level	Console/	build, composer:merge, composer:scripts, db:check-collation, dev, pint, refresh, replace:regex, version
Update	Console/Update/	Module-update commands

→ Per-command usage is documented in the Console guide.

---

Controllers

Directory: src/Http/Controllers/ · Namespace: Unusualify\Modularous\Http\Controllers

The controller hierarchy is CoreController → PanelController → BaseController. Modules extend BaseController and configure form schemas, with each layer adding more module-aware behaviour.

Layer	Purpose
CoreController	Base HTTP controller — shared response helpers
PanelController	Route/model resolution, index options, authorization, $this->repository
BaseController	View prefix, form schema, index/create/edit flow, setupFormSchema()

BaseController traits: ManageIndexAjax, ManageInertia, ManagePrevious, ManageSingleton, ManageTranslations.

Request flow: preload() → addWiths() → setupFormSchema() → index() / create() / edit() → respondToIndexAjax() for AJAX.

Concrete controllers (selection): ApiController, ChatController, DashboardController, FileLibraryController, FilepondController, MediaLibraryController, MetricController, ProcessController, ProfileController, TagController, UiPreferencesController, plus auth-scoped controllers under Http/Controllers/Auth/.

→ Full Controllers reference

---

Entities

Directory: src/Entities/ · Namespace: Unusualify\Modularous\Entities

~30 Eloquent models for users, content, files, processes, state, and communication, plus supporting Casts/, Enums/, Interfaces/, Mutators/, Observers/, Scopes/, Traits/, and Translations/ subfolders. Module-generated models extend Model and gain soft-deletes, tagging, caching, presenter support, and trait composition out of the box.

Group	Models	Reference
Base classes	Model, Revision	Model → · Revision →
Communication	Chat, ChatMessage	Chat → · ChatMessage →
Content building blocks	Block, Repeater, Tag, Tagged	Block → · Repeater → · Tag →
Files & Media	File, Filepond, Media, TemporaryFilepond	File → · Filepond → · Media →
Other	Feature, NestedsetCollection, RelatedItem	Feature → · NestedsetCollection → · RelatedItem →
Process & Workflow	Assignment, Authorization, CreatorRecord, Process, ProcessHistory	Assignment → · Authorization → · Process →
State & Data	Setting, Singleton, Spread, State, Stateable	Singleton → · State → · Stateable →
Users & Auth	Company, Profile, User, UserOauth	Company → · Profile → · User →

Enums: AssignmentStatus, PaymentStatus, Permission, ProcessStatus, RoleTeam, UserRole.

→ Full Entities reference

---

Entity Traits

Directory: src/Entities/Traits/ · Namespace: Unusualify\Modularous\Entities\Traits

A library of traits (top-level + nested under Auth/, Core/, Secondary/) covering relationships, accessors, scopes, lifecycle hooks, and broadcasting context. Each trait composes onto an entity to add a self-contained behaviour without subclassing.

Group	Examples	Reference
Auth	CanRegister, HasOauth	Auth →
Core (top-level)	HasPosition, HasPresenter, HasSlug, HasSpreadable, HasStateable, HasUuid	Core →
Media	HasFileponds, HasFiles, HasImages	Media →
Model behavior	HasPosition, HasPresenter, HasSlug, HasSpreadable, HasStateable, HasUuid	Model behavior →
Payment	HasPayment, HasPriceable	Payment →
Processes	HasProcesses, Processable	Processes →
Relationships	Assignable, Chatable, HasAuthorizable, HasCreator	Relationships →
Repeaters	HasRepeaters	Repeaters →
Secondary	HasBlocks, HasNesting, HasRelated, HasRevisions	Secondary →
Singletons	IsHostable, IsSingular	Singletons →
Translation	HasTranslation, IsTranslatable	Translation →

→ Full Entity Traits reference

---

Events & Listeners

Directory: src/Events/, src/Listeners/ · Namespace: Unusualify\Modularous\Events, Unusualify\Modularous\Listeners

Events fire at lifecycle boundaries (model created/updated, user registered, state changed). Listeners react and, when mail is enabled, dispatch the matching notification.

Class	Role	Page
Listener	Abstract base for listeners — resolves notification class from event name	Class reference
ModelEvent	Abstract base — composes EventChanges, EventStateable, EventUrls, EventUser traits and provides broadcasting defaults	Class reference
User events	ModularousUserRegistered, ModularousUserRegistering, ModularousUserVerification, VerifiedEmailRegister	Auth events

Event traits (under events/traits/): EventChanges, EventStateable, EventUrls, EventUser. Each is auto-set up in ModelEvent's constructor and its public properties are serialized into broadcast payloads.

→ Full Events reference → Real-time setup, Echo integration, testing, and troubleshooting are covered in the Broadcasting guide.

---

Facades

Directory: src/Facades/ · Namespace: Unusualify\Modularous\Facades

21 Laravel facades providing static-style access to bound services. Each facade aliases a container entry to a concrete service class.

Selected facades: Coverage, CurrencyExchange, Filepond, HostRouting, MigrationBackup, Modularous, ModularousCache, ModularousRoutes, ModularousVite, Navigation, Redirect, Register, RelationshipGraph, SiteSettings, SystemSettings, CmsSettings, Utm.

Settings deep-dive: Settings Services.

→ Full Facades reference

---

Form Requests

Directory: src/Http/Requests/ · Namespace: Unusualify\Modularous\Http\Requests

Form Request classes that validate, authorize, and shape incoming requests for module endpoints. Extend Laravel's FormRequest with module-aware authorization and translation hooks.

Class	Purpose
BaseFormRequest	Shared validation/authorization plumbing
FileRequest	File upload validation
MediaRequest	Media upload validation
OAuthRequest	OAuth callback payload validation
Request	Generic module-aware base form request
StorePermissionRequest	Permission creation
StoreRoleRequest	Role creation

→ Full Form Requests reference

---

Generators

Directory: src/Generators/ · Namespace: Unusualify\Modularous\Generators

Scaffolding engine behind make:* and make:route commands. Produces the full PHP and JS file set for new module routes plus test scaffolding for both backend and frontend.

Generator (abstract)                ← NwidartGenerator + ReplacementTrait
├── RouteGenerator                  ← full-stack route scaffolding (primary)
├── StubsGenerator                  ← stub-only regeneration (fix/patch)
├── VueTestGenerator                ← Vitest/Jest test scaffolding
└── LaravelTestGenerator            ← PHPUnit test scaffolding

Generator	Responsibility
Generator	Abstract base — module resolution, config path helpers
LaravelTestGenerator	PHPUnit Unit or Feature test scaffolding
RouteGenerator	Full set of files for a new module route (model, migration, controller, repository, request, translations, permissions)
StubsGenerator	Selective stub regeneration with only / except lists
VueTestGenerator	Vue component / composable / utility / store test scaffolding

→ Full Generators reference

---

Helpers

Directory: src/Helpers/ · Namespace: global functions

15 PHP helper files exposing 100+ global functions. Loaded by Composer autoload, available everywhere.

File	What it covers
array	Array shape transforms
column	Column metadata helpers
component	Frontend component resolution
composer	Composer JSON parsing
connector	External-service connector helpers
db	Schema introspection (hasColumn, hasIndex, etc.)
format	Currency / date / number formatting
front	Frontend URL/asset helpers
i18n	Locale and translation helpers
input	Input schema / hydrate helpers
media	Image URL / disk resolution
migrations	Migration build helpers
module	modularousConfig(), module_path(), currentModule()
router	Route resolution helpers
sources	Module path discovery

→ Full Helpers reference

---

Middleware

Directory: src/Http/Middleware/ · Namespace: Unusualify\Modularous\Http\Middleware

14 middleware classes registered via BaseServiceProvider and grouped into pipelines for admin, auth, and API routes.

Middleware	Purpose
Authenticate	Modularous-aware auth guard
Authorization	Permission/role enforcement
CompanyRegistration	Company onboarding gate
HandleInertiaRequests	Inertia shared props
Hostable	Host-based routing resolution
Impersonate	User impersonation gate
Language	Locale resolution from URL/header
LoadLocalizedConfig	Locale-specific config loading
Log	Request logging
Navigation	Sidebar nav assembly
RedirectIfAuthenticated	Guest-only routes
Redirector	Configured redirect rules
TeamsPermission	Team-aware permission resolution
Utm	UTM parameter capture

→ Full Middleware reference

---

Notifications

Directory: src/Notifications/ · Namespace: Unusualify\Modularous\Notifications

Group	Classes	Page
Auth notifications	EmailVerification, GeneratePasswordNotification, ResetPasswordNotification	Auth notifications →
Feature base	FeatureNotification	FeatureNotification →
System notifications	11 system notification classes (model lifecycle, payments, assignments, chat, state changes)	System notifications →

Notifications are dispatched by Listener::handle() when modularous.mail.enabled = true and the listener resolves a {EventName}Notification class.

→ Full Notifications reference

---

Providers

Directory: src/Providers/ · Namespace: Unusualify\Modularous\Providers

Service providers wire the package into the host Laravel app. Bind services, publish config, register routes, hook view composers, wire the scheduler, and discover commands.

Provider	Role
AuthServiceProvider	Modularous policies and gates
BaseServiceProvider	Core bindings, command discovery, view composers, scheduler, middleware aliases
CoverageServiceProvider	Coverage analyzer + commands binding
ModularousProvider	Top-level provider — registers all child providers
ModuleServiceProvider	Per-module provider auto-generated for each module
RouteServiceProvider	Module route registration with host/permission groups
ServiceProvider	Abstract base with config publishing helpers
TelescopeServiceProvider	Telescope integration when present

→ Full Providers reference

---

Repository Traits

Directory: src/Repositories/Traits/ · Namespace: Unusualify\Modularous\Repositories\Traits

Repository traits extend the base Repository class with domain-specific persistence logic. While Entity Traits define model-level behaviour, repository traits handle how data flows in and out — form field hydration, after-save side effects, table filters, caching.

Every repository trait follows a naming convention that the base Repository discovers and invokes at the right lifecycle stage:

Convention	When called
setColumns{Trait}	Boot — registers form input names this trait manages
prepareFieldsBeforeCreate{Trait}	Before insert
prepareFieldsBeforeSave{Trait}	Before any save
beforeSave{Trait} / afterSave{Trait}	Around the Eloquent save() call
hydrate{Trait}	Sets in-memory relationships before save (preview/validation)
getFormFields{Trait}	Populates form fields when editing
afterDelete{Trait} / afterRestore{Trait}	Soft-delete + restore hooks
filter{Trait} / order{Trait}	Index query scopes / ordering
getTableFilters{Trait}	Filter tab definitions for the data table UI
getFormActions{Trait}	Form action button definitions

Group	Page
Content (Blocks, Repeaters)	Content →
Logic helpers (caching, schema, query building)	Logic →
Media (Files, Images, Filepond)	Media →
OAuth	OAuth →
Payment	Payment →
Processes	Processes →
Relationships	Relationships →
State	State →

→ Full Repository Traits reference

---

Scheduled Jobs

Directory: src/Schedulers/ · Namespace: Unusualify\Modularous\Schedulers

Background jobs auto-discovered from src/Schedulers/*.php via CommandDiscovery and registered against Laravel's Schedule inside BaseServiceProvider::boot() (no Console\Kernel.php is required in the host app).

Command	Class	Cadence	Purpose
modularous:fileponds:scheduler	FilepondsScheduler	Daily	Cleans up orphaned temporary_fileponds rows + their files
modularous:scheduler:chatable	ChatableScheduler	Every minute	Aggregates unread chat messages and dispatches UnreadChatMessage notifications
telescope:prune	(Laravel Telescope)	Daily	Prunes Telescope entries older than 168 hours

Both Modularous schedulers can also be run manually as Artisan commands. Output goes to the scheduler log channel; the host server only needs the standard * * * * * php artisan schedule:run cron entry.

→ Full Scheduled Jobs reference

---

Services

Directory: src/Services/ · Namespace: Unusualify\Modularous\Services

Bound in the service container; injected via constructor or accessed through their dedicated Facades. Each group has its own reference page.

Group	Members	Page
Cache concerns	CacheHelpers, CacheInvalidation, CacheTags	Cache Concerns →
Core services	Assets, BroadcastManager, Connector, CoverageService, CurrencyExchangeService, FilepondManager, FileTranslation, MessageStage, MigrationBackup, ModularousCacheService, RedirectService, Translation, UtmParameters	Services →
Currency	NullCurrencyProvider, SystemPricingCurrencyProvider	Currency →
Settings	AbstractSingularSettingsService, SystemSettingsService, CmsSettingsService, SiteSettingsService	Settings →
FileLibrary	Disk, FileService	FileLibrary →
MediaLibrary	Glide, Imgix, Local, TwicPics drivers	MediaLibrary →
Uploader	SignAzureUpload, SignS3Upload, SignUploadListener	Uploader →
View services	ModularousNavigation, UComponent, UWidget, UWrapper	View Services →

Cache support: CacheRelationshipGraph drives cross-entity cache invalidation. The CLI face is cache:graph.

→ Full Services reference

---

Support

Directory: src/Support/ · Namespace: Unusualify\Modularous\Support

Stateless utility classes used across the codebase for command discovery, schema parsing, route grouping, and host-based routing.

Class	Purpose
CommandDiscovery	Scan glob paths and return instantiable Command FQCNs
CoverageAnalyzer	Parse Clover XML and report per-method coverage
Decomposers	Parse schema/relation/validation strings for generators
FileLoader	Translation file loader with multi-path support
Finder	Resolve model/repository by table name or route name
HostRouting / HostRouteRegistrar	Multi-tenant host-based route groups
Migrations\SchemaParser	Render migration $table->… PHP from schema strings
ModularousRoutes	Route group options and middleware alias registration
ModularousVite	Vite integration for the Modularous asset manifest
RegexReplacement	Batch regex find-and-replace across a directory tree

→ Full Support reference

---

View Composers

Directory: src/Http/ViewComposers/ · Namespace: Unusualify\Modularous\Http\ViewComposers

Inject shared variables into Blade / Inertia layouts. Wired in BaseServiceProvider::registerViewComposers().

Composer	Views	Condition
ActiveNavigation	layouts with sidebar	Always
CurrentUser	admin.*, {baseKey}::*	enabled.users-management = true
FilesUploaderConfig	master/app-inertia layouts	enabled.file-library = true
Localization	master/auth/app-inertia layouts	Always
MediasUploaderConfig	master/app-inertia layouts	enabled.media-library = true
Urls	*	Always

→ Full View Composers reference

---

Cross-cutting concerns

A few capabilities don't live in a single section — they thread through several layers at once. Subsections below are ordered alphabetically; use them as a map to find every place a given concern shows up.

Authentication, authorization & registration

Auth is split between the request pipeline (middleware), the Spatie permission stack (gates/policies), and a verification-token broker for self-service registration.

Layer	Component
Brokers	RegisterBroker, RegisterBrokerManager, TokenRepositoryInterface
Controllers	Http/Controllers/Auth/*
Entities & Traits	Company, Profile, User, UserOauth; CanRegister, HasOauth
Enums	Permission, RoleTeam, UserRole
Form Requests	OAuthRequest, StorePermissionRequest, StoreRoleRequest
Middleware	Authenticate, Authorization, CompanyRegistration, Impersonate, RedirectIfAuthenticated, TeamsPermission
Notifications	EmailVerification, GeneratePasswordNotification, ResetPasswordNotification
Providers	AuthServiceProvider

Caching

Modularous ships a versioned, tag-aware cache built on top of Laravel's cache. Invalidation propagates through a relationship graph so editing a model also flushes anything that depends on it.

Layer	Component
Bind / boot	BaseServiceProvider (registers ModularousCacheService, CacheRelationshipGraph)
CLI	cache:clear, cache:graph, cache:list, cache:stats, cache:versions, cache:warm
Concerns	CacheHelpers, CacheInvalidation, CacheTags
Day-to-day API	ModularousCache facade, CacheRelationshipGraph
Repository hooks	Repository Traits → Logic (afterSave{Trait}, afterDelete{Trait})

→ Full deep-dive: ModularousCacheService.

File & media uploads

Three independent upload pipelines share the same general shape (Form Request → Service → Entity Trait).

Pipeline	Controller	Service	Entity Trait	Repository Trait
Direct cloud uploads	—	Uploader (SignAzureUpload, SignS3Upload)	—	—
File library	FileLibraryController	FileLibrary	HasFiles	Media
Filepond (chunked uploads)	FilepondController	FilepondManager	HasFileponds	Media
Media library (image variants)	MediaLibraryController	MediaLibrary	HasImages	Media

Module scaffolding & generation

Build-time only — these run from the CLI to produce or regenerate code.

Layer	Component
CLI	make:* commands (Console Commands)
Generators	Generator, LaravelTestGenerator, RouteGenerator, StubsGenerator, VueTestGenerator
Support	Decomposers, Migrations\SchemaParser, RegexReplacement

→ End-to-end walkthrough: Modules reference.

Multi-tenant / host-based routing

When the same module needs to serve different domains with different middleware or permission groups.

Layer	Component
Entity Traits	IsHostable, IsSingular
Facade	HostRouting
Middleware	Hostable
Provider	RouteServiceProvider
Support	HostRouting / HostRouteRegistrar, ModularousRoutes

Real-time broadcasting

Model lifecycle and chat events broadcast over Laravel Echo when broadcasting is enabled.

Layer	Component
Base classes	Listener, ModelEvent (with event traits)
Entity Traits	Chatable, HasProcesses, HasStateable, Processable
Notifications	System notifications (model lifecycle, payments, assignments, chat, state changes)
Scheduled job	ChatableScheduler
Service	BroadcastManager

→ Setup, channel naming, Echo client, testing, and troubleshooting: Broadcasting guide.

---

→ Looking for something not covered above? Browse the system reference index or jump straight into the per-section overview pages linked from each heading.