Frontend Architecture — Next.js 15 Dashboard¶

Part: Sass-boilerplate-frontend-v1/ | Type: Web Application Generated: 2026-02-12 | Last Modified: 2026-03-26 | Scan Level: Exhaustive | Workflow: document-project v1.2.0

Executive Summary¶

Next.js 15 dashboard application using App Router with React 19. Features a modular component architecture with Radix UI primitives (shadcn/ui pattern), Redux Toolkit for auth state, TanStack React Query for server state, and TailwindCSS 4 for styling. Provides both public-facing pages (blog, landing, contact) and a protected admin dashboard. Includes security hardening (DOMPurify XSS prevention across all 9 dangerouslySetInnerHTML sites, iframe sandboxing), dynamic theme/font customization, a cache revalidation dashboard, drag-and-drop menu builder v2, and an AI voice integration module.

Language¶

This frontend is written in JavaScript (.js / .jsx files), not TypeScript. While the backend uses TypeScript and all frontend tooling (Next.js, Redux Toolkit, React Query) has first-class TypeScript support, the frontend currently does not use type checking. A TypeScript migration is possible but not yet implemented.

File counts (verified 2026-03-26): 413 total .js/.jsx files — 74 pages, 4 layouts, 31 API hook files, 42 UI components, 33 custom components, 15 editor components, 128 page components, 9 layout components, 5 providers, 7 theme-control components, 10 custom hooks, 3 services, 10 lib/utils, 3 constants, 2 Redux slices, 2 server action files (4 functions).

Technology Stack¶

Note: Two charting libraries coexist. ApexCharts is used for the main dashboard analytics; Recharts is used for supplementary visualizations. Consider consolidating to one library to reduce bundle size (~150KB combined).

Directory Structure¶

Sass-boilerplate-frontend-v1/
├── src/
│   ├── app/                         # Next.js App Router (74 pages)
│   │   ├── layout.js                # Root layout — provider hierarchy
│   │   ├── globals.css              # Global styles + TailwindCSS
│   │   ├── (auth)/                  # Auth route group (public)
│   │   │   ├── layout.js           # Auth layout with FooterCredit
│   │   │   ├── login/page.js
│   │   │   ├── register/page.js
│   │   │   └── verify-email/[token]/page.js
│   │   ├── (dashboard-layout)/      # Dashboard route group (protected)
│   │   │   └── dashboard/
│   │   │       ├── layout.js        # Dashboard layout (sidebar + topnav)
│   │   │       ├── page.js          # Dashboard home
│   │   │       ├── analytics/       # Analytics page
│   │   │       ├── users/           # User management
│   │   │       ├── blogs/           # Blog management (5 pages incl. tags)
│   │   │       ├── packages/        # Package management (4 pages)
│   │   │       ├── products/        # Product management (4 pages)
│   │   │       ├── pages/           # CMS pages (3 pages)
│   │   │       ├── roles-permissions/ # RBAC management (3 pages)
│   │   │       ├── settings/        # Settings (7 pages: account, site, profile, menu-builder, menu-builder-old, menu-label, revalidate)
│   │   │       ├── contacts/        # Contact submissions
│   │   │       ├── email-templates/ # Email template visual builder (3 pages: list, create, edit)
│   │   │       ├── invited-users/   # User invitations
│   │   │       ├── pricing-plan/    # Pricing display
│   │   │       ├── ai-integration/  # AI voice interview with speech recognition
│   │   │       ├── ai-integration-old/ # Legacy AI integration (dead code candidate)
│   │   │       ├── auth/            # Auth page templates (5 variants)
│   │   │       ├── form-elements/   # Form showcase (6 pages)
│   │   │       ├── table/           # Table showcase (4 pages: basic, advanced, v2 variants)
│   │   │       ├── test/            # Test pages (nested 3 levels)
│   │   │       └── [UI demos]/      # accordion, alerts, avatar, breadcrumb, carousel, pagination
│   │   ├── (main-layout)/          # Public route group
│   │   │   ├── layout.js
│   │   │   ├── page.js             # Landing/home page
│   │   │   ├── blogs/              # Public blog (3 pages incl. tags)
│   │   │   ├── contact/            # Contact form
│   │   │   ├── author/[slug]/      # Author profile
│   │   │   ├── category/[slug]/    # Category listing
│   │   │   └── [slug]/             # Dynamic CMS pages
│   │   ├── forgot-password/page.js
│   │   └── reset-password/[token]/page.js
│   ├── components/                  # Reusable components
│   │   ├── ui/                      # 42 base UI components (Radix + shadcn pattern)
│   │   ├── custom/                  # 33 custom business components
│   │   ├── pages/                   # 128 page-specific compositions
│   │   ├── layout/                  # 9 layout components (sidebar, topnav)
│   │   ├── common/                  # Shared business components
│   │   ├── forms/                   # Form components
│   │   ├── charts/                  # Chart components
│   │   ├── tables/                  # Data table components
│   │   ├── editor/                  # 15 rich text editors (13 BlockNote + 2 custom BasicEditor)
│   │   ├── providers/               # 5 context providers
│   │   └── theme-control/           # 7 theme customization UI components
│   ├── api/                         # React Query hooks (20 domains, 139 hooks across 31 files)
│   │   ├── auth/                    # Login, register, verify, reset (6 hooks)
│   │   ├── blogs/                   # Blog CRUD + categories + tags (12 hooks)
│   │   ├── blog-categories/         # Legacy hook (1, double-prefix bug)
│   │   ├── blog-tags/               # Legacy hook (1, double-prefix bug)
│   │   ├── contacts/               # Contact submissions + bulk ops (8 hooks)
│   │   ├── dashboard/              # Analytics data (1 hook)
│   │   ├── email-templates/        # Template management (10 hooks)
│   │   ├── google-fonts/           # Google Fonts API (1 hook)
│   │   ├── invited-users/          # Invitation + resend + check (12 hooks)
│   │   ├── menu/                   # Menu CRUD (6 hooks)
│   │   ├── menu-builder/           # Menu builder + reorder + tree (13 hooks + 4 utils)
│   │   ├── menu-item/              # Menu item operations (3 hooks)
│   │   ├── menu-labels/            # Legacy hook (1, double-prefix bug)
│   │   ├── packages/               # Package management (10 hooks)
│   │   ├── package-categories/     # Legacy hook (1, double-prefix bug)
│   │   ├── pages/                  # CMS page CRUD (10 hooks)
│   │   ├── permissions/            # Permission CRUD (10 hooks)
│   │   ├── products/               # EMPTY — no hooks exported (BUG)
│   │   ├── product-categories/     # Legacy hook (1, double-prefix bug — not used)
│   │   ├── public/                 # Server-side fetching (7 server fns + 1 client hook)
│   │   ├── revalidate/             # Cache revalidation (3 hooks — NEW)
│   │   ├── roles/                  # Role management (9 hooks)
│   │   ├── settings/               # Settings by group (5 hooks)
│   │   ├── account-settings/       # Account settings (4 hooks)
│   │   └── users/                  # User management (11 hooks)
│   ├── store/                       # Redux store
│   │   ├── index.js                 # Store configuration
│   │   └── slices/
│   │       ├── authSlice.js         # Auth state (user, token, isAuthenticated)
│   │       └── settingSlice.js      # Site settings by group
│   ├── hooks/                       # 10 custom hooks
│   │   ├── useCheckPermission.js    # RBAC permission check
│   │   ├── useCheckSlug.js          # Slug uniqueness validation
│   │   ├── useClientPathName.jsx    # Client-side pathname
│   │   ├── useDashboardData.js      # Dashboard analytics
│   │   ├── useDebounce.jsx          # Input debouncing
│   │   ├── useFormSubmit.js         # Form submission handler
│   │   ├── useMediaQuery.jsx        # Responsive breakpoints
│   │   ├── useMenus.js             # Navigation menu fetching
│   │   ├── useRedux.js             # Typed Redux hooks
│   │   └── useTableActions.js       # Table CRUD operations
│   ├── services/                    # 3 service files
│   │   ├── authService.js           # Auth API methods
│   │   ├── menuService.js           # Menu data (permanently hardcoded to dummy data)
│   │   └── menuItemService.js       # Menu item data (permanently hardcoded to dummy data)
│   ├── interceptors/
│   │   └── axiosInstance.js         # Axios config + auth interceptors
│   ├── context/                     # React context definitions
│   ├── actions/                     # Server actions (2 files, 4 functions)
│   ├── hocs/                        # Higher-order components
│   ├── constants/                   # 3 static constants files
│   ├── lib/                         # 10 utility files (cn(), formatters)
│   ├── assets/                      # Static assets
│   └── middleware.js                # Next.js route middleware
├── package.json
├── CLAUDE.md                        # AI assistant context
└── README.md

Route Map (74 Pages)¶

Authentication (5 pages)¶

Dashboard — Core (3 pages)¶

Dashboard — Content Management (10 pages)¶

Dashboard — E-Commerce (9 pages)¶

Dashboard — Administration (14 pages)¶

Public Pages (8 pages)¶

UI Showcase Pages (~25 pages)¶

Auth templates (5), form elements (6), table variants (4 including v2 variants), accordion, alerts, avatar, breadcrumb, carousel, pagination, components, test pages (nested 3 levels).

Permission-Protected Pages (4 pages, 5 checks)¶

Warning: Only 4 out of ~50 dashboard pages enforce client-side permission checks. All other pages rely solely on middleware auth (logged-in check) and backend permission validation.

Provider Hierarchy¶

// app/layout.js
<ReduxProvider store={store}>
  <QueryProvider>
    <AuthInitializer>
      <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
        <Toaster position="top-right" />
        {children}
      </ThemeProvider>
    </AuthInitializer>
  </QueryProvider>
</ReduxProvider>

Authentication Architecture¶

1. Middleware (middleware.js)¶

• Protects /dashboard/* routes — redirects to /login if no token cookie
• Redirects authenticated users from /login, /register → /dashboard
• Matcher: ["/login", "/register", "/dashboard/:path*"]

2. Redux Store (2 Slices)¶

Auth Slice (authSlice.js):

initialState: { user: null, token: null, isAuthenticated: false }
reducers: setAuth, logout, initializeAuth, updateUser

Setting Slice (settingSlice.js):

initialState: { settings: {} }
reducers: setSettings
selectors: getSettingByGroup(group)

Known bug: Store config registers this as settinReducer (typo — missing 'g').

3. Axios Interceptor¶

• Request: Adds Authorization: Bearer {token} from cookie
• Response: On 401/403 → deletes cookie, dispatches logout, redirects to /login
• Connected to Redux via setStoreDispatch() from AuthInitializer

Known bug: 403 (Forbidden) triggers full logout + redirect. Only 401 (Unauthorized) should trigger logout; 403 should show an "access denied" message instead, since the user is authenticated but lacks permission.

4. Auth Initializer¶

• Runs on mount: syncs Redux from cookie + wires Redux dispatch to axios

State Management¶

Known issue — Triple-cache desync: Three independent caching layers (React Query, Redux settingSlice, Next.js fetch cache) can hold stale versions of the same data. No synchronization mechanism exists between them.

UI Component Library (42 Components)¶

Base UI components in components/ui/ following shadcn/ui pattern with Radix primitives:

Layout: card, sheet, collapsible, accordion, tabs Input: input, textarea, label, checkbox, radio-group, select, searchable-dropdown, SearchableDropdown (PascalCase duplicate), multi-select, slider, switch, date-inputs, calendar Display: badge, avatar, progress, skeleton, dashboard-skeletons, chart, code-box, heading, section-heading, author-card, sandboxed-html-preview, sanitized-html-preview Feedback: alert, alert-dialog, dialog, tooltip, popover, spinner, loading Navigation: button, breadcrumb, dropdown-menu, command Theme: theme-toggle

Note: SearchableDropdown.jsx and searchable-dropdown.jsx both exist — naming inconsistency that could cause import confusion.

Custom Components (33 Components)¶

Business-level components in components/custom/ including modals, permission wrappers, data tables, image upload, pagination, status badges, and form fields. Notable components:

• PermissionWrapper — renders children only if user has required permission (render-phase redirect side effect)
• Modal system — custom modal used by 32+ consumers (zero accessibility attributes)
• DataTable — generic table with sorting, pagination, bulk actions
• ImageUpload — drag-and-drop with preview

Note: Two Button components coexist (ui/button vs custom/button) used interchangeably across flows. Three competing modal systems: custom/modal (32 consumers, zero a11y) vs ui/dialog (5 consumers, full a11y) vs ui/alert-dialog (never imported anywhere).

API Integration Layer¶

Hook Architecture¶

// api/{domain}/index.js
export const useItems = (params) => useQuery({
  queryKey: ["{domain}", params],
  queryFn: () => api.get("/{endpoint}", { params }).then(r => r.data),
});

export const useCreateItem = () => {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (data) => api.post("/{endpoint}", data),
    onSuccess: () => qc.invalidateQueries({ queryKey: ["{domain}"] }),
  });
};

API Hook Domains (139 hooks across 31 files in 25 domains)¶

Legacy hooks: 4 files (blog-categories, blog-tags, menu-labels, package-categories) contain useEffect-based data fetching that duplicates existing React Query hooks. All 4 have double-prefix URL bugs (e.g., /api/api/blog-categories).

Server-Side Data Fetching¶

Public pages use Next.js fetch() with cache tags for ISR-style revalidation. The project does not use unstable_cache or generateStaticParams.

Server Functions (src/api/public/)¶

7 server functions + 1 client hook:

Cache Configuration¶

• Revalidation time: NEXT_PUBLIC_CACHE_TIME env var (default: 1 hour)
• 7 cache tags in use: blogs, blog-details, dynamic-page, navigation-links, packages-data, settings-group, all-settings
• Revalidation triggered via dashboard at /dashboard/settings/revalidate

Cache Revalidation System (NEW)¶

Added in the 2026-03-12 to 2026-03-26 sprint. Provides a dashboard UI for on-demand cache invalidation.

• Protected by cache.view + cache.update permissions
• Targets all 7 cache tags listed above
• Uses Next.js server actions for tag-based revalidation

Menu Builder v2 (NEW)¶

Replaced the legacy menu builder with a WordPress-style drag-and-drop hierarchy system.

Pricing Section Refactor (NEW)¶

The pricing section was refactored to support monthly/yearly toggle:

• PricingContent — handles monthly/yearly switching logic
• PricingSection — wrapper/container, separated from content logic

Custom Hooks¶

Dynamic Metadata¶

// app/layout.js
export async function generateMetadata() {
  const settings = await fetch(`${API_URL}/settings/admin/prefix`);
  // Parses "admin.meta_title" → nested object
  return { title: settings.admin.meta_title || "Sass Boilerplate" };
}

Theme Customization¶

Dynamic theme and font system:

• Font families loaded from Google Fonts API (useGoogleFonts hook with localStorage caching)
• Font settings stored in site settings and applied via CSS custom properties
• Poppins font import removed from root layout (fonts now dynamic)

Security Hardening¶

Note: SanitizedHTMLPreview and SandboxedHtmlPreview are the two approved patterns for rendering user-supplied HTML. All new features should use one of these instead of raw dangerouslySetInnerHTML.

Environment Variables¶

Development Commands¶

npm run dev     # Start with Turbopack (port 3000)
npm run build   # Production build
npm start       # Start production server
npm run lint    # ESLint (Next.js core-web-vitals)

Styling¶

• TailwindCSS 4 with @tailwindcss/postcss
• Dynamic fonts via Google Fonts API (Poppins removed; fonts now configurable via settings)
• Dark mode via class attribute + next-themes
• shadcn/ui component pattern with CSS variables for theming
• tw-animate-css for animation utilities
• @/ import alias for src/ directory

Known issue: gold color tokens are completely undefined in Tailwind config (16 uses across 7 files fail silently). light-50 is also missing a @theme mapping (15 uses across 10 files).

Known Issues¶

Dead Code Candidates (~30 files, ~4000+ LOC)¶

Files that appear unused or superseded. Removal candidates pending verification:

Total removable: ~30 files, ~4000+ LOC. Removing these would reduce bundle size and maintenance burden.

Generated by BMAD Document Project workflow v1.2.0 — Exhaustive scan, 2026-02-12 | Last modified: 2026-03-26