Appearance

Brand Portal Frontend ​

Overview ​

Welcome to the Brand Portal Frontend Developer Guide. This comprehensive documentation covers all features, components, pages, and integrations for the Brand Portal Frontend application.

Quick Start ​

The Brand Portal Frontend (source: brand-portal) is a Nuxt 4 application with all source code under app/ (srcDir: 'app/'). It provides a modern, secure brand portal with features including:

  • Dashboard & Homepage: Promotional banners, resource tiles, trending assets, and recent uploads
  • Authentication: Secure HTTP-only cookie-based authentication with token-based login
  • Search & Discovery: Powerful search capabilities with Typesense integration and advanced filtering
  • Asset Management: View, download, and manage digital assets
  • Folder Management: Hierarchical folder navigation and organization
  • Collage Management: Create and manage collages (collections of assets)
  • Sharing System: Secure sharing with permissions, passwords, and expiration dates
  • Real-time Features: Live updates via Pusher WebSocket integration
  • Download System: Advanced download system for assets and folders

Documentation Sections ​

Features ​

Comprehensive documentation of all core features and systems:

  • Dashboard & Homepage
  • Authentication System
  • Search & Discovery
  • Asset Management
  • Folder Management
  • Collage Management
  • Sharing System
  • Profile Management
  • Real-time Features
  • Download System
  • Typesense Integration

Pages ​

Documentation for all application pages (20 pages total):

  • Authentication Pages (5): Login, Forgot Password, Reset Password, Generate Password, Token Login
  • Main Application Pages (5): Dashboard, Search, Profile, Sharing, Support
  • Folder Pages (2): Folders List, Folder Details
  • Collage Pages (2): Collage List, Collage Details
  • Asset Pages (1): File Details
  • Utility Pages (3): Root Index, Get Assets, Shared Assets

Components ​

Reusable Vue components used throughout the application:

  • Card Components (4): AssetCard, AssetContainer, CollageCard, FolderCard (under card/ and card/Asset/)
  • Dashboard Components (2): Tile, Resource
  • Dialog Components (4): ShareAssetDialog, QuickViewDialog, ConfirmationDialog, AssetConverterDialog
  • Global Components (6): Header, SideBar, SidebarFolderTree, Snackbar, Notification, Error
  • Preview Components (2): PdfJsViewer, TxtViewer
  • Miscellaneous Components (6): AsyncIcon, BreadCrumbs, ViewToggle, CollageLoader, GridViewSkeleton, ListViewSkeleton
  • Search Components (9): SearchBar, SearchAssets, SearchFilter, SearchBulkActions, SearchTableHeader, AddedFilterOption, ListLevelThree, SearchGridAssetsSkeleton, SearchListSkeleton
  • Sharing Components (3): ShareLinkListTable, ShareTableHeader, ShareTableListItem
  • SVG Components (100+): Icon components in svg/ (e.g. used via AsyncIcon)

Composables ​

Reusable composition functions (79 total; see Composables index for the full list):

  • Authentication Composables (4): useAuth, useCookieHelper, customScheme, usePublicPortal
  • API Composables (composables/api/): useAuthApi, useAppDataApi, useAssetsApi, useSearchApi, useSharingApi, useFolderApi, useCollectionApi, useProfileApi, useDownloadApi, useWorkspaceApi, useAccountApi, useExternalShareApi, useNotificationApi, useShareDialogApi, useSupportApi, useCommonApis, useFetchClient; TanStack Query: useAppDataQueries, useAssetsQueries, useCollectionQueries, useFolderQueries, useProfileQueries, useSharingQueries, useQueryClient, useMutationClient, queryKeys
  • Core Common Composables: useHelpers, useAnalytics, useBreadCrumbs, useFileType, useImageStyle, useViewModeCache, useAccountStatus, useToggleSelection, useRouteFromMiddleware, useCarouselSettings, useBrandingColors, useCommonSearch, useSearchUtils
  • Component Composables: Card, Dialog, Search, Sharing, Header, Notification composables
  • Layout Composables: useCollageSidebar, useSidebarFolderTree, useSidebarCurrentFolder
  • Miscellaneous Composables: useSnackbar, useCrypto, usePdfJs, usePdfJsViewer, useTxtViewer
  • Page Composables: useDashboard, useSearch, useFolders, useCollage, useCollageDetails, useSharing, useProfile, useSupport, useFolderDetails, useAssetDetails, useExternalShare

Stores ​

Pinia store modules and state management (with optional persistence via pinia-plugin-persistedstate):

  • Authentication store
  • Application data store (appData, with caching)
  • Search store
  • Download store
  • Analytics store

Server APIs | Composable APIs ​

Server-side API routes and integration:

  • Server APIs (Internal Nuxt routes): Authentication (set-session, clear-session, session, refresh-user, debug), Pusher WebSocket auth, Typesense search API, PDF proxy (/api/pdf/proxy), TXT proxy (/api/txt/proxy)
  • Composable APIs (app/composables/api/): useAuthApi, useAppDataApi, useAssetsApi, useSearchApi, useSharingApi, useFolderApi, useCollectionApi, useProfileApi, useDownloadApi, useWorkspaceApi, useAccountApi, useExternalShareApi, useNotificationApi, useShareDialogApi, useSupportApi, useCommonApis, useFetchClient; plus TanStack Query composables (use*Queries, useQueryClient, useMutationClient, queryKeys)

Middleware ​

Route protection and access control:

  • Global authentication middleware (auth.global.ts)
  • Per-route authentication middleware (auth.ts)
  • URL validation and brand verification (check-url.ts)
  • Redirect middleware (redirect-if-logged-in)
  • Public portal middleware (public-portal-home, public-portal-login-redirect, public-portal-search)

Types ​

TypeScript type definitions:

  • Common types (Asset, Folder, FileItem, etc.)
  • Component types (Props, Emits)
  • API types (Request/Response interfaces)
  • Store types (State, Actions, Getters)
  • Composable types (Return types)

Utils ​

Shared utility modules in app/utils/:

  • error.ts — getApiErrorMessage for consistent API error display (used by Vue Query plugin and snackbars)
  • cancelTokenManager.ts — AbortController management for request cancellation and throttling

Constants ​

Application constants in app/constants/:

  • domains.ts — MAIN_APP_HOSTS, isMainAppHost, hostWithoutPort; used by check-url middleware and Error/verify-domain logic

Plugins ​

Nuxt plugins and initialization (load order is critical):

  • Pinia store setup
  • API client configuration
  • TanStack Vue Query (caching, deduplication, global error handling, SSR)
  • Auth initialization (01.auth-init.ts)
  • Vuetify configuration
  • PDF.js client
  • Laravel Echo (Pusher) client
  • StreamSaver for downloads
  • Snackbar, Mitt event bus, Vue Audio Visual
  • Branding colors (client)

Styling (SCSS) ​

Comprehensive SCSS architecture and styling system (42+ style files):

  • Architecture: 7-1 Pattern organization with modern SCSS syntax (@use/@forward)
  • Abstracts (3 files): Variables (color palette, typography, spacing), mixins (responsive, flexbox, transitions), functions
  • Base (3 files): Reset styles, typography (Inter/Space Grotesk), utility classes (gaps, margins, scrollbars)
  • Layout (5 files): Header, sidebar, breadcrumbs, layout containers, announcements
  • Components (24 files): Buttons, forms, cards, tables, dialogs, chips, checkboxes, radio, switches, selects, datepicker, tooltips, snackbar, skeleton loaders, carousel, image groups, and more
  • Pages (5 files): Login, asset detail, collage detail, settings, error pages
  • Design System:
    • Color palette with 100-900 scale (red, pink, lavender, cream, teal, orange, blue, gray, black, green)
    • Typography scale (10-34px) with consistent font families
    • Spacing system (xs: 4px to xl: 24px)
    • Border radius and shadow standards
  • Responsive Design: Mobile-first with breakpoints (mobile: ≤960px, tablet: ≤1280px, desktop: ≥1281px, large: ≥1640px, xl: ≥1920px)
  • Variable Auto-Injection: Variables automatically available via Vite configuration

Layouts ​

Application layouts and page structure:

  • Collage layout (main app layout)
  • Default layout (minimal layout)
  • Login layout (authentication pages)
  • Error layout (error pages)

Getting Started ​

  1. Start with Features Overview to understand the core systems
  2. Review Authentication System for secure access
  3. Explore Dashboard & Homepage for the main user interface
  4. Check Pages to see how features are implemented
  5. Review Components for reusable UI elements

Architecture ​

The Brand Portal Frontend is built with:

  • Framework: Nuxt 4.1.3 (srcDir: 'app/' — all source under app/)
  • UI Library: Vuetify 3.10.5
  • State Management: Pinia 3.0.3, TanStack Vue Query 5 (server state, caching, mutations)
  • Search Engine: Typesense 2.1.0
  • Real-time: Laravel Echo + Pusher
  • Language: TypeScript 5.9.3
  • Styling: SCSS (7-1 Pattern in app/assets/scss/)
  • Auto-imports: composables, utils, stores, constants (types are explicit from ~/types)

Key Features ​

Dashboard & Homepage ​

  • Promotional banner carousel
  • Resource tiles (grid or slider view)
  • Trending assets carousel
  • Recent uploads organized by file type
  • Performance optimizations with caching

Authentication System ​

  • HTTP-only cookie-based authentication
  • Token-based login for password-less access
  • Password recovery and reset
  • Automatic session management
  • XSS protection and secure token storage

Search & Discovery ​

  • Full-text search with Typesense
  • Advanced filtering (tags, file types, dates)
  • Encrypted URL state management
  • Real-time search results
  • Bulk actions on search results

Asset Management ​

  • Asset viewing with preview
  • Asset downloading (single and bulk)
  • Asset sharing
  • Multiple file type support
  • Quick view and full preview dialogs

Folder Management ​

  • Hierarchical folder navigation
  • Breadcrumb navigation
  • Grid and list view modes
  • Sorting and filtering
  • Bulk operations

Collage Management ​

  • Create and manage collages
  • Organize assets into collections
  • Collage sharing
  • Collage-based asset operations

Sharing System ​

  • Share links with permissions
  • Password protection
  • Expiration dates
  • Embed codes
  • Share link management

Real-time Features ​

  • Pusher WebSocket integration
  • Secure WebSocket authentication
  • Live notifications
  • Real-time data synchronization

Source repository: brand-portal
Last Updated: February 2026
Version: 1.1.0