TruCMS Architecture Overview

How a request travels through TruCMS, which services exist, and where the extension points sit. Every later chapter assumes this mental model.

Boot sequence

Laravel 13 bootstraps from bootstrap/app.php:

• Routing — routes/web.php (web group), routes/api.php, routes/console.php, health check at /up.
• Global middleware — proxies, CORS, maintenance, post-size, trim/empty-to-null, then RedirectToInstallMiddleware, which sends every request to the installer's preinstall route until dotartisan.installed is true (except install/*).
• web group — cookies, session, error sharing, SetLocale (localized routes), route-model binding, AuthenticateSession, then DemoClearance (a write guard for the two demo accounts when APP_DEMO is on).
• CSRF exceptions — install/* and webhooks/*.

Middleware aliases you can use on routes

Service providers

Listed in bootstrap/providers.php:

Module providers boot inside LaravelModulesServiceProvider, so anything that must see all registrations (widgets, binding-source watchers, reserved slugs) is deferred with $app->booted(...).

The three request families

Admin requests

GET /admin/pages
  -> web group
  -> routes/web.php : Route::middleware([AdminTheme])->as('admin.')->prefix('admin')
  -> routes/admin.php : auth, verified, 2fa  ->  ->can('manage page')  ->  PageController@index
  -> view('pages.index')  resolved in resources/themes/admin/pages/index.blade.php

AdminTheme::handle() does five things, in order:

1. Selects the admin theme (setting('admin_theme'), default admin).
2. AdminAsideMenu::register() — registers the core sidebar entries for the current user's permissions into MenuManager.
3. RegisterSettings::register() — registers all core settings sections into SettingsManager.
4. On admin.menus* routes, BuilderMenu fills the menu-builder sources.
5. Dispatches App\Events\AdminBooting. Every module listens to it to add its own sidebar items, settings sections and menu-builder sources.

Public requests

GET /about
  -> web group
  -> catch-all route 'resolve.show'  (FrontendRoutingServiceProvider)
  -> FrontTheme, TwoFactorMiddleware, doCache
  -> ResolvePathController@show -> SlugResolver
  -> slugs row -> sluggable model -> resolvedSlugRenderer() -> renderer->render()
  -> view('pages.show')   (resources/themes/echo/pages/show.blade.php)

Fixed routes (/, /contact, /blog, /category/{category}, /tag/{tag}, auth pages and the /user/* account area) are declared in routes/front.php, routes/app.php and routes/auth.php. Anything else at the first URL segment is treated as a slug (pages, posts, booking services, shop products). That is why modules reserve their own segments with public_paths in module.json. See Page types and public URLs.

Public routes are wrapped in Route::localized(...) where translation is supported, so locale prefixes such as /ar/about are handled by codezero/laravel-localized-routes.

Module requests

A module's RouteServiceProvider wraps its route files in the same theme middleware:

Modules/Booking/app/Providers/RouteServiceProvider.php

Route::middleware(['web', 'auth', AdminTheme::class])
    ->as('admin.booking.')
    ->prefix(config('dotartisan.admin_prefix', 'admin') . '/bookings')
    ->group(module_path($this->name, '/routes/admin.php'));

Core routes/*.php files neverrequire module routes. Disabling a module removes its routes, menu entries, widgets and scheduled tasks; its database tables stay.

Rendering model: themes and views

TruCMS ships three themes in resources/themes/:

igaster/laravel-theme adds the active theme's folder to Laravel's view paths, so view('layouts.app-layout') resolves to resources/themes/echo/layouts/app-layout.blade.php and a child theme can override any view by providing the same relative path.

Module views are namespaced (booking::admin.dashboard). The theme view finder searches for an override before the module's own folder, in resources/themes/{active theme}/vendor/{namespace}/… — for example resources/themes/echo/vendor/booking/admin/dashboard.blade.php. Views published to resources/views/modules/{alias} are mapped onto {theme}/modules/{alias}. This is how a theme restyles a module without editing it.

The hook layer: registries and facades

DotartisanServiceProvider binds string-keyed singletons that are exposed through facades. These are the extension points for modules and themes:

Registries are plain objects rebuilt on every request. Whatever you register must therefore run in every request that needs it. That is why menu and settings registrations happen inside an AdminBooting listener, while shortcodes, widgets and binding sources are registered in the provider's boot().

Persistence model

Caching layers

1. Response cache stores whole public HTML pages for guests (and per user for signed-in users). Opt in per route with doCache; never cache state-changing pages.
2. Model and key caches via the ClearCache trait on BaseModel, plus manual Cache::remember for menus, languages, countries and widget areas.
3. Compiled theme CSS written to storage/app/public/css/themes/{theme}/app.css when theme options change.
4. Laravel caches (config, route, view); dotartisan:optimize and dotartisan:cache-views are the project's "safe" variants.

See Caching and performance.

Background work

• QUEUE_CONNECTION defaults to sync; choose a real driver in production if you queue anything.
• The core has one job (RefreshBoundPages). Business modules schedule their own commands from configureSchedules() in their provider. routes/console.php schedules pages:refresh-bound hourly.
• The server cron must run php artisan schedule:run every minute.

Cross-cutting guards