# CLAUDE.md Guidance for Claude when working in this repository. Read it fully before writing any code. ## 1. About the project This is a **Laravel-based CMS template / starter kit** (similar to WordPress, but built with Laravel). It is **not a shared product**. The workflow: 1. The template is copied into a new repo for each client (e.g. an oil company, an educational institution). 2. Unused modules are removed and client-specific modules are added. 3. The frontend is rebuilt per client inside the same repo. Consequences: - Each client has its own repo, database, and server. **There is no multi-tenancy.** - Code must be easy to **understand, cut down, and modify**. Prefer simplicity over abstraction. - Removing a module must be clean: delete its folder and disable it in `config/modules.php`. ## 2. Tech stack | Area | Choice | |---|---| | Framework | Laravel 13, PHP 8.3 to 8.5 (minimum 8.3) | | Database | MySQL / MariaDB (SQLite-compatible for testing) | | Admin panel | **Blade + Livewire 3 + Alpine.js + Tailwind CSS** (custom-built) | | Public frontend | Blade + Tailwind (minimal starter, rebuilt per client) | | Rich text editor | Tiptap (via Alpine component) | | Permissions | `spatie/laravel-permission` | | Media | `spatie/laravel-medialibrary` + Intervention Image (WebP) | | Activity log | `spatie/laravel-activitylog` | | Backup | `spatie/laravel-backup` | | Sitemap | `spatie/laravel-sitemap` | | Slugs | `spatie/laravel-sluggable` | | Auth | Laravel Fortify (login, password reset, 2FA) | | Testing | Pest | | Code style | Laravel Pint | ### Hard rules - **Do NOT use Filament, Nova, Backpack, Voyager, or any other third-party admin panel.** The admin is built in-house with Blade components + Livewire. - Do not add new packages without a clear reason. Ask first if unsure. - Do not add Inertia, Vue, or React. The stack is server-rendered. ### Laravel 13 specifics - The documentation reference is **laravel.com/docs/13.x**. Do not follow patterns from versions 11/12 if they changed in 13. When in doubt, check the 13.x docs first. - Follow the current Laravel skeleton: middleware, exceptions, and routing are configured in `bootstrap/app.php`; there is **no `app/Http/Kernel.php`**. - Laravel 13 supports **PHP Attributes** as an alternative to class properties for configuring components. They may be used when more concise, but stay **consistent**: pick one style per component type and do not mix them. - Use PHP 8.3+ features where they help (typed class constants, `readonly` classes, `#[\Override]`). - **Before installing any package**, confirm it is compatible with Laravel 13 (check the package's `composer.json` or run `composer require` and read the resolution result). If a package is incompatible, report it and propose alternatives. Do not downgrade the framework. - The Laravel AI SDK and built-in vector search are **not used** in this template (out of scope for a CMS). Do not add them unless asked. - Make sure local, staging, and production all run PHP 8.3+, since `composer update` fails on PHP 8.2. ## 3. Directory structure ``` app/ Core/ # foundation shared by all modules Support/ # helpers, traits, base classes Livewire/ # generic admin components (DataTable, MediaPicker, etc.) Http/Middleware/ # RedirectManager, CheckModuleEnabled, EnsureInstalled, etc. Providers/ Setup/ # setup wizard: Actions (shared with app:install), Livewire steps, lock file logic Modules/ Article/ # CORE Page/ # CORE Category/ # CORE (categories & tags) Media/ # CORE Seo/ # CORE Setting/ # CORE User/ # CORE (users, roles, permissions) Comment/ # optional (visitor comments on articles, moderation; requires Article) Activity/ # optional (read-only activity log page) Backup/ # optional (backups page: list, run, download, delete) Transfer/ # optional (import and export of articles, pages, categories and tags as JSON) Analytics/ # optional (page views of articles and pages: counts per day, totals in lists, dashboard chart; listens to ContentViewed) Revision/ # optional (a version per save of articles and pages, compare and restore; autosave of unsaved form changes per person) Update/ # optional (daily check of release.json: new DigiCMS release and module versions in System > Updates and the bell; update:manifest) # Add-ons (Menu, Redirect, Contact, Banner, Gallery, Testimonial, Faq, Newsletter) are NOT in the template: # they live in the sibling folder ../digi-template-addons and are copied in per client (see its README). config/ modules.php # list of enabled modules resources/ views/ admin/ # admin layout & pages (never mix with frontend) components/admin/ # admin Blade components (table, form, modal, etc.) frontend/ # CLIENT AREA: public layout & pages js/ admin.js frontend.js routes/ web.php # loads frontend routes admin.php # admin routes (prefix /admin, auth middleware) database/ seeders/ CoreSeeder.php # roles, permissions, default settings (required) DemoSeeder.php # sample content (safe to delete) ``` ### Structure of a single module Every module is **self-contained**: ``` app/Modules/Article/ Models/ Http/ Controllers/ # frontend & admin controllers Requests/ Livewire/ # admin tables/forms for this module Policies/ Actions/ Database/ Migrations/ Seeders/ Resources/ views/ admin/ frontend/ # default views (clients may override) lang/ routes/ admin.php web.php ArticleServiceProvider.php module.php # metadata: name, description, requires, permissions, admin menu (group, icon), notices, charts, recent ``` Each module has a `ServiceProvider` that registers routes, views (namespace `article::`), migrations, and translations. The provider is loaded only if the module is enabled in `config/modules.php`. ## 4. Code conventions ### General - PSR-12 via Pint. Run `vendor/bin/pint` before finishing. - `declare(strict_types=1);` in new PHP files. - Type hints and return types on all methods. - Use **Form Requests** for validation, not inline validation in controllers. - Keep controllers thin. Complex business logic goes into **Action classes** (`app/Modules/X/Actions/`) or Services. - Use **Policies** for authorization. Every admin action must check permissions. - Use PHP enums for statuses (`ArticleStatus::Draft`, etc.), not raw strings. - Avoid N+1 queries: eager load, and enable `Model::preventLazyLoading()` in non-production environments. ### Naming - Tables: plural snake_case (`articles`, `article_tag`). - Models: singular PascalCase (`Article`). - Permissions: `module.action` (e.g. `article.create`, `article.publish`, `media.delete`). - Route names: `admin.article.index`, `article.show` (frontend). - Module view namespace: `article::admin.index`. ### Database - All migrations must be **reversible** (correct `down()`). - Use `softDeletes()` for main content (articles, pages). - Add indexes for frequently filtered columns (`status`, `published_at`, `slug`). - Never edit a migration that has already run in a template used by a client. Create a new migration instead. ## 5. Building the admin (without Filament) Because there is no CRUD generator, we maintain **our own admin components** so new modules are quick to build and the UI stays consistent. Components that must exist in `app/Core/Livewire` and `resources/views/components/admin`: - `DataTable` (Livewire): search, filters, sorting, pagination, bulk actions, per-page selector. - Form components: input, textarea, select, toggle, date picker, slug input, tag input. - `RichEditor` (Alpine + Tiptap) with server-side HTML sanitization. - `MediaPicker` (modal for choosing/uploading from the media library). - `SeoFields` (meta title, description, canonical, robots, OG) with a Google result preview. - Confirmation modal, toast notifications, empty state, admin breadcrumb. - Responsive admin layout (collapsible sidebar, mobile-friendly). Rules: - The admin sidebar is built automatically from each enabled module's `module.php`. - All admin pages use the layout `resources/views/admin/layouts/app.blade.php`. - Use Livewire for interactions (tables, forms with realtime validation). Use Alpine for small client-side interactions. - Do not write custom CSS when Tailwind utilities are enough. ### Admin look and feel (shadcn-admin, rebuilt in Blade) The admin follows the design of **shadcn/ui and shadcn-admin** (zinc neutrals, a green primary taken from the DigiCMS logo, rounded cards with thin borders, a grouped collapsible sidebar, light and dark mode). It is rebuilt with Blade + Tailwind, **not** with React: the hard rule above (no React/Vue/Inertia) still stands, so never copy shadcn-admin's React code, only its design. - **Tokens, not colours.** `resources/css/admin.css` defines the design tokens as CSS variables for light and dark (`--background`, `--card`, `--primary`, `--muted`, `--border`, `--destructive`, `--sidebar` ...). Use the semantic utilities: `bg-background`, `bg-card`, `bg-muted`, `text-foreground`, `text-muted-foreground`, `border-border`, `text-destructive`, `bg-primary`. **Never** hard-code `bg-white`, `text-black`, or `gray-*` / `red-*` shades in admin views: they break dark mode. `AdminThemeTest` fails the build if you do. Change the brand colour in one place: the `--primary` pair in `admin.css`. - **Colours.** Tokens: `primary` (green: the main action), `info` (blue), `warning` (amber), `destructive` (red), each with a `-foreground`. ``; row actions take `tone="primary|info|warning|destructive"` by meaning (edit = info, view/approve/restore = primary, unapprove/spam/disable = warning, delete = destructive). - **Tables.** A row's actions are `` with one `` per action (icon only, `tone="destructive"` for delete; inside a component tag use `{{ Js::from() }}` not `@js`). Text in a cell is cut to 30 characters with "..." by the DataTable (column option `limit`, `0` = never; `nowrap` for a column that must stay on one line; `responsive` => 'xl' or '2xl' hides a column below that screen width); in a custom cell use ``. - **Build with the components** in `resources/views/components/admin/`: `button` (variants default, secondary, info, warning, destructive, outline, ghost, link; sizes default, sm, icon), `input`, `textarea`, `select`, `toggle` (a switch), `card`, `badge` (variants success, warning, info, secondary, destructive, outline), `page-header`, `breadcrumb`, `empty-state`, `modal`, `confirm-dialog`, `toasts`, `icon`, `row-actions` and `row-action`, `truncate`, `chart-bars` and `chart-donut`, `avatar`, `language-switcher`, `timezone-select`, `command-palette`, `rich-editor`, `seo-fields`, `slug-input`, `tag-input`. Do not restyle them per page. Status badges: give the enum a `badgeVariant()` and print ``. Do not mix an inline `@php(...)` with a `@php ... @endphp` block in one Blade file, and do not use `@js()` or `@class()` inside a component tag (`BladeDirectivesTest` catches both). - **Icons** are Lucide-style inline SVG: ``. Add a new icon by adding its markup to the map in `icon.blade.php`. - **Sidebar and dashboard come from `module.php`.** Each `menu` entry takes `group` (one of `ModuleRegistry::GROUPS`: Content, Media, Engagement, Users, System, Settings) and `icon`. Every group is a fold in the sidebar (the one with the open page, and the first, start open; the choice is remembered). A menu entry may carry `expand` (`source` class + `method`) to stand for several entries: Settings does this, one entry per settings group (General, Contact, SEO, Comments ...), each at `/admin/settings/{group}`. A settings group has a `label`, an `icon`, a `description` and optional `sections` (a field names its section) in `settings.php`. A group is shown in the sidebar as an entry with the icon of `ModuleRegistry::GROUP_ICONS`; one with a single page is that page. - **Dashboard.** No total cards. Charts come from `charts` (`label`, `type` 'bars' with a `date` column or 'donut' with a `group` column, `model`, optional `scope`, `permission`, `route`, `order`), drawn as SVG by `` and `` (no JS chart library); a module may add a "Latest ..." list with `recent` (`label`, `model`, `title`, `route` taking the id, `permission`, optional enum `status`). "Needs your attention" shows the `notices` and, for people who may change settings, `SecurityChecks::problems()`. - **Modules page.** Settings > Modules lists every module (core ones are locked on) and switches the optional ones on and off with `ModuleSwitcher`, which edits `config/modules.php` as text, runs the migrations and seeds the permissions of a module that is switched on, and refuses when another enabled module needs it. It needs the permission `module.manage` and is closed in production, where `config/modules.php` ships with the code. - **Page views.** The Article and Page controllers fire `ContentViewed` (not for previews); the Analytics module listens, skips bots, prefetch, staff and a repeat visit the same day (settings), and adds to one row per item per day in `page_views`. A chart declares `sum` to add a column per day; a `recent` list may name a `source` class instead of a model. - **Footer.** The admin layout ends with ``: the template version (`TEMPLATE_VERSION`) and "Built by Digitalku" linking to https://digitalku.com. It is hidden by `ADMIN_FOOTER=false` (`config('app.admin_footer')`); keep it in the layout, a client project edits the component. - **Notifications bell.** A module lists things that need attention under `notices` in `module.php` (`label`, `route`, `permission`, `icon`, and `model` + `scope` or `source` + `method` returning a count). Zero counts are hidden. - **Command palette (Ctrl/Cmd+K).** It lists the sidebar pages and the `commands` a module declares in `module.php` (`label`, `route`, `permission`, `icon`, optional `order`: the "Create ..." shortcuts, which the dashboard also shows as quick actions), filtered by the person's permissions. Give a module with a create page a command. - **Accounts.** Your own profile (`/admin/profile`: name, email, picture, password, two-factor with Fortify's actions, each sensitive step asks for the current password). A user can be invited by email (they choose their own password), disabled (cannot sign in, sessions ended; `EnsureAccountIsActive` signs them out mid-session) and never the last active super admin. Show a person with ``. - **Two-factor reminder.** `` in the admin layout covers every admin page (not the profile) for a person without confirmed two-factor authentication, with "Set it up now" (profile `#two-factor`) and "Skip for now" (`admin.two-factor-prompt.skip`, stores `users.two_factor_prompt_skipped_at`; back after `TwoFactorPrompt::SKIP_HOURS` = 24). Logic in `App\Modules\User\Support\TwoFactorPrompt`; `ADMIN_TWO_FACTOR_PROMPT=false` (`config('app.admin_two_factor_prompt')`) switches it off. - **Media.** Files can be put in folders, replaced in place (same id, same kind of file) and show where they are used: a module that uses library files registers a finder with `MediaUsageRegistry` in its provider (see Article). - **Dark mode** is toggled from the header and remembered in `localStorage`; an inline script in `` applies it before the first paint. Do not rely on `prefers-color-scheme` alone. - `stubs/module/` already follows all of this; keep new stubs on tokens too. ## 6. SEO guidelines This template must make SEO easy for the frontend developer: - A `HasSeo` trait on models (Article, Page, etc.) providing a relation to the polymorphic `seo_meta` table. - A Blade component `` that renders: title, meta description, canonical, robots, Open Graph, Twitter Card, and JSON-LD. - Automatic fallbacks: if meta fields are empty, use the content's title, excerpt, and thumbnail. - `sitemap.xml` generated automatically (scheduler/command) from published models. - `robots.txt` editable from the admin (stored in settings). - **Redirect manager** (Redirect add-on; core fires `SlugChanged`): a middleware matching URLs against a `redirects` table (301/302). When a slug changes, a redirect is created automatically. - RSS feed for articles. - Canonical URLs are always absolute and consistent. ## 7. Frontend helpers The frontend developer (me, per client) must be able to build pages without touching core logic. Provide: ```php setting('site_name'); // fetch a setting (cached) setting('contact.email', 'default'); menu('header'); // fetch a menu as a tree (Menu add-on) module_enabled('gallery'); // check whether a module is enabled ``` ```blade @foreach (menu('footer') as $item) ... @endforeach {{-- Menu add-on --}} ``` A view composer exposes `$siteSettings` to the frontend layout. Add-ons and shared views (the same applies to optional modules): Blade resolves `` tags **when it compiles a view**, so an `@if (module_enabled('banner'))` around `` does not protect a site where that module is off (it fails with "Unable to locate a class or view for component"). Views that every site uses (the starter layout and home page, core modules) may only use components of core modules. Reach optional ones with `` inside the `module_enabled()` check. A test (`OptionalModuleViewsTest`) enforces this. ## 7b. Multi-language The site can be in several languages (English and Indonesian ship; add more in `config/locales.php`). With a single entry in `available` every language control disappears. There are two separate things, and both are tested: **Interface language** (admin screens, forms, emails, validation messages) - Write every visible string as `__('English text')`; the English text is the key. Never build sentences by concatenation: use placeholders, `__('Delete :name?', ['name' => $x])`, and `trans_choice` for plurals. - Translations live in `lang/id.json` (plus `lang/id/validation.php`, `auth.php`, `passwords.php`, `pagination.php`). A module may ship its own `Resources/lang/id.json`, which is loaded automatically when the module is enabled; add-ons use this. - Definitions that are data (menu `label` and `group` in `module.php`, dashboard `charts`, `recent` and `notices`, `settings.php` labels and hints, DataTable column, filter and bulk-action labels, breadcrumb labels, enum `label()`) keep plain English and are translated **where they are printed**. Toast messages are translated by `WithToast` and the toasts component. - Do not use a string that equals a framework translation file name as a key (`'Pagination'` returns an array): the test suite catches it. - `TranslationTest` fails when a `__()` string, a menu or settings label has no Indonesian text, when a translation drops a `:placeholder`, or when the framework messages are incomplete. Add the Indonesian text with the English one. - The admin language is the cookie `admin_locale` (switcher in the admin header); the public site uses the cookie `locale`. `SetLocale` (web group) applies them; Livewire requests are matched to admin or site by their Referer. - **Default language is `config('locales.default')` (`APP_LOCALE`), never `config('app.locale')`**: Laravel rewrites `app.locale` for each request. Use `App\Core\Support\Locales` (`default()`, `codes()`, `multiple()`, `isValid()`). **Content language** (articles, pages, categories, translatable settings) - One row per language ("Polylang style"): each version is a complete record with its own title, slug, status and SEO, and the versions of one piece of content share `translation_group`. Columns `locale` and `translation_group` come from `TranslationColumns::add($table)` in a migration; the model uses the `Translatable` trait (`inLocale()`, `otherTranslations()`, `translationUrls()`, `missingLocales()`, `createTranslation($locale)`). - To make another module translatable: the migration, the trait, a language field in its form (`WithTranslations` + ``), `localeColumn()`/`localeFilter()` in its table, `->inLocale()` in its public queries, and `translationUrls()` for the switcher. Tags, redirects and menu items are not translated rows. - Public pages: filter with `->inLocale()`; a detail page resolves its slug in any language and calls `Locales::adopt($model->locale)`, so a shared link opens in the right language. Pass `translationUrls()` to `` (section `language_switcher`) and `` adds `hreflang` links by itself. - Settings: `'translatable' => true` in `settings.php`; other languages are stored as `key@locale` and fall back to the default language's value. - Changing a version's language after it is saved is not allowed (it would break the one-version-per-language rule); a new version is created from the Language card of the form. ## 7c. Dates, time zone and site settings - The database keeps **UTC** (`config('app.timezone')` stays `'UTC'`; do not change it). The site's time zone, date format and time format are settings (Settings > General) and are applied where dates are shown or typed. - Show a date with `site_date($d)`, `site_time($d)` or `site_datetime($d)`; never `->format('Y-m-d')` on a model date in a view or table. For a `datetime-local` input use `SiteFormat::toInput($date)` to fill it and `SiteFormat::fromInput($string)` to read it back (it returns UTC). `site_timezone()` is the zone name. - The favicon is a Media library image id (`site_favicon`); layouts print `site_favicon_url() ?? asset('favicon.png')`. - The **Address** setting (`site_address`) overrides `config('app.url')` for public pages and console commands so absolute links (sitemap, canonical, social cards) use it. It is **never** applied to `admin`, sign-in, `livewire` or `setup` (`SiteFormat::isPrivateRequest`), so a wrong address cannot lock anyone out. - A module can add settings with its own `app/Modules//settings.php` (same format as the Setting module's). Field types: text, email, url, number, textarea, select, timezone, media, password (stored encrypted, never sent back to the browser, blank keeps the saved value; mark it `'secret' => true` so it stays out of `$siteSettings`). Each group is a page of its own under Settings in the sidebar (`/admin/settings/{group}`) with a `label`, an `icon`, a `description`, optional `sections` (cards with a title) and fields that name their `section`. Shipped: General, Contact, Email (SMTP in the database, applied by `MailSettings`, `.env` stays in effect until "How to send" is chosen; test email; docs/email.md), SEO, Media (largest upload), Articles (per page, feed length), Comments, Activity log (retention), Page views, Revisions (versions kept, autosave interval). ## 8b. Security headers, rate limits and the frontend cache - `SecurityHeaders` (outermost middleware) sends the headers and the Content-Security-Policy from `config/security.php`. The public site's policy allows **no inline or eval scripts**: do not add `