Frontend

Server-rendered BXM views, small Alpine.js components, and a Vite-compiled SCSS/JS pipeline.

Frontend

How it fits together

The frontend is a hybrid server-rendered + Alpine.js application - no SPA, no client-side router:

Alpine.js architecture

App.js (entry)
  ├── Registers all Alpine stores + components
  ├── Imports Bootstrap JS + Phosphor icons + Tippy.js
  │
  ├── Stores ($store.*)
  │   ├── theme.js     → dark/light mode, syncs data-bs-theme + localStorage
  │   └── sidebar.js   → collapse/open, mobile overlay, localStorage persistence
  │
  └── Components (x-data)
      ├── auth/        → AuthForm, RegisterForm, ForgotPasswordForm, PasswordResetForm
    ├── security/     → AuditLogForm, PermissionsForm, RolesForm, UserDetailForm, UsersForm
    ├── profile/      → PasskeyOnboarding, PreferencesForm, ProfileForm
    ├── settings/     → SettingsForm, SettingsRegistryForm
    └── ui/           → Drawer, GlobalProgress, GlobalToast, Logo, MessageBox, PasswordMeter, PasswordStrength, Switch

Each component is a standalone module returning an Alpine x-data object:

export default () => ( {
    visible: true,
    init() {
        setTimeout( () => this.visible = false, 5000 );
    }
} );

<div x-data="messageBox" x-show="visible" x-transition>
    <!-- alert content -->
</div>

SCSS structure

app.scss
  ├── _variables.scss   Bootstrap variable overrides
  ├── bootstrap          Full Bootstrap 5.3 import
  ├── _base.scss         CSS custom properties (light/dark theme)
  ├── components/        9 component partials
  ├── layouts/            Admin + Auth layout partials
  └── views/              Page-specific styles

Vite configuration

vite.config.mjs uses coldbox-vite-plugin's coldbox() plugin:

• Entry points: resources/assets/scss/app.scss and resources/assets/js/App.js
• refresh: appRefreshPaths — auto full-reload on handler/view changes
• publicDirectory: "public/includes" — where built assets land
• SCSS preprocessor with silenceDeprecations flags for newer Dart Sass (import, global-builtin, color-functions, if-function)

npm run dev        # Vite dev server with HMR
npm run build      # Production build → public/includes/
npm run lint       # ESLint check on resources/assets/js
npm run lint:fix   # ESLint auto-fix
npm run lint:scss  # Stylelint on resources/assets/scss

Server-rendered view components

These BXM partials live under app/views/_components/ and are rendered with ColdBox's view() helper. They are intentionally presentation-focused: pass values through the args struct and keep business logic in handlers or services.

Application shell

Authentication partials

UI partials

Alpine components and stores

resources/assets/js/App.js registers the following names globally with Alpine. Use them as x-data="name" or x-data="name(...)" in BXM views. Form components make remote requests to the matching handler routes and expect the CSRF token supplied by their view.

Application shell and authentication

Admin and profile forms

UI components and global APIs

The source also contains Header.js, Sidebar.js, TopBarNotifications.js, and Logo.js. Their exports are available for local imports, but they are not currently registered by App.js; register them with Alpine.data() before using them as global x-data components.

Stores, utilities, and magic properties

AlpinePlugins.js installs Collapse, Focus, Mask, and Persist. passkeys.js provides the browser-side WebAuthn integration. Keep new reusable browser APIs documented here and add their registration/import to App.js when they are global.

Avatars & branding logo

User avatars and the application branding logo are stored on the private cbfs assets disk (see Configuration) and streamed out by Assets.bx (see Handlers & Routing) rather than served as static files.

• Display goes through the _components/ui/avatar partial: it renders <img src="/avatars/:userId/:size"> when hasAvatar is true, and falls back to an initials <span> otherwise. It is wired into the sidebar, topbar, and Users listing table (server-projected hasAvatar field), and inline in the Users detail page (x-show/x-cloak toggling on user.hasAvatar, since that page's avatar sits inside an Alpine-driven summary card rather than a static partial).
• Upload/remove for the current user's own avatar lives on the Profile page, owned by profileForm (ProfileForm.js): a hidden file input reads the selected image as a base64 data URI (readFileAsDataUrl()) and posts it to POST /profile/avatar; DELETE /profile/avatar removes it. Both bump a version counter used as a cache-busting query param on the streamed URL, since the file path itself does not change between uploads.
• The branding logo gets the same upload/remove treatment on the Settings page, via the logoUploader component (LogoUploader.js) against POST/DELETE /settings/logo. It replaces the cbAppLogo setting's text input value with the streamed path (/branding/logo/lg) on upload, and restores the configured default on removal — the manual URL text input and live <img> preview keep working exactly as before for anyone who wants to point cbAppLogo at an external URL instead.
• Both upload endpoints accept the same shapes: images are decoded server-side with BaseSecureHandler.decodeDataUri(), then resized/cropped into sm/lg JPEG (avatar) or PNG (logo) variants by ImageService (app/models/system/ImageService.bx).