Project Structure

This page describes the top-level directory layout, the purpose of every major folder, and the file-naming conventions used throughout the project.

Directory tree

jumbo-react-next/
├── @assets/                  # Static assets accessed via @assets/ alias
│   └── fonts/
│       └── noir-pro/         # Noir Pro font files and CSS
├── @jumbo/                   # @jumbo component framework (path alias: @jumbo/)
│   ├── components/           # JumboLayout, JumboTheme, JumboNavbar, etc.
│   ├── shared/               # Primitive wrappers: Link, Div, Span, CardIconText
│   ├── types/                # TypeScript types for all @jumbo components
│   ├── utilities/            # helpers, formatHelpers, styleHelpers, constants
│   └── vendors/
│       └── react-hook-form/  # JumboForm and field components
├── docs/                     # Migration guides and internal notes
│   └── v7-to-v8-migration-guide/
├── e2e/                      # Playwright end-to-end test suite
├── src/                      # Application source (alias: @/)
│   ├── app/                  # Next.js App Router
│   │   ├── [lang]/           # Dynamic locale segment
│   │   │   ├── layout.tsx    # Root layout (providers, theme, auth)
│   │   │   ├── (common)/     # Default layout — routes without a demo prefix
│   │   │   ├── (solo)/       # Minimal layout — auth pages, error pages
│   │   │   ├── (demo1-layout)/  # Demo 1 layout — routes under /demo-1/
│   │   │   ├── (demo2-layout)/  # Demo 2 layout — routes under /demo-2/
│   │   │   ├── (demo3-layout)/  # Demo 3 layout — routes under /demo-3/
│   │   │   └── (demo4-layout)/  # Demo 4 layout — routes under /demo-4/
│   │   └── api/
│   │       ├── auth/[...nextauth]/  # Auth.js route handler
│   │       └── menus/[locale]/      # Menu items API endpoint
│   ├── components/           # Feature and UI components
│   ├── config/               # App configuration (theme, routes, layouts)
│   │   ├── index.ts          # Root CONFIG object
│   │   ├── routes/path.ts    # Public and anonymous route lists
│   │   └── layouts/default.ts  # Default layout options
│   ├── dictionaries/         # i18n JSON translation files
│   ├── layouts/              # Sub-layout components (SettingLayoutContent)
│   ├── lib/
│   │   └── auth/             # Server-side auth helpers
│   ├── proxy/                # Locale and auth proxy handlers
│   │   ├── auth.ts           # handleAuth, handleAnonymousRoute
│   │   └── locale.ts         # handleLocale, pathnameHasLocale
│   ├── services/             # Data service layer (menus)
│   ├── styles/               # Global CSS
│   ├── themes/               # MUI theme tokens
│   │   ├── main/             # default.ts, dark.ts, semi-dark.ts
│   │   ├── header/           # default.ts, dark.ts, semi-dark.ts
│   │   ├── sidebar/          # default.ts, dark.ts, semi-dark.ts
│   │   └── footer/           # default.ts, dark.ts, semi-dark.ts
│   └── utilities/            # App-level helpers and constants
├── auth.ts                   # Auth.js v5 config (root level, included in tsconfig)
├── next.config.js            # Next.js configuration
├── next-auth.d.ts            # Session/JWT type augmentation
├── tsconfig.json             # TypeScript config with path aliases
├── vitest.config.ts          # Vitest configuration
├── vitest.setup.ts           # Testing Library jest-dom setup
├── playwright.config.ts      # Playwright E2E configuration
├── .env.example              # Environment variable template
└── package.json              # Dependencies and scripts

Key directories

Directory	Purpose
`@jumbo/`	First-party component framework — layout engine, theme system, form components, utilities
`@assets/`	Static assets (fonts) accessed via the `@assets/` TypeScript alias
`src/app/[lang]/`	App Router root; the `[lang]` segment provides URL-based i18n
`src/app/[lang]/(common)/`	Default layout group; all main app pages live here
`src/app/[lang]/(solo)/`	Bare layout for auth, error, and lock-screen pages
`src/app/[lang]/(demo*-layout)/`	Four alternate demo layouts with distinct themes and headers
`src/components/`	Feature components shared across pages (dashboards, apps, widgets)
`src/config/`	Central app configuration: theme, route lists, and layout defaults
`src/dictionaries/`	Translation JSON files for six locales
`src/proxy/`	Next.js proxy handlers for locale detection and auth routing
`src/themes/`	MUI token files for main, header, sidebar, and footer regions
`src/lib/auth/`	Server-side session helpers: `getSession`, `isAuthenticated`, `hasRole`
`e2e/`	Playwright test files and page object models

Key files

File	Purpose
`auth.ts`	Auth.js v5 config — Credentials provider, JWT callbacks, `signIn`/`signOut` exports
`next-auth.d.ts`	Extends `Session`, `User`, and `JWT` with `id`, `role`, `accessToken`
`src/proxy.ts`	Root proxy function — called from `middleware.ts`; orchestrates locale + auth
`src/app/[lang]/layout.tsx`	Root HTML shell with all providers: MUI cache, theme, auth, i18n, dialog, snackbar
`src/config/index.ts`	Exports the `CONFIG` object: `THEME`, `PUBLIC_ROUTES`, `ANONYMOUS_ROUTES`
`src/config/layouts/default.ts`	`defaultLayoutConfig` used by the `(common)` layout group
`next.config.js`	Security headers, `/` redirect, and image domain allowlist
`vitest.config.ts`	Test runner config with 80% coverage thresholds and path alias resolution

Naming conventions

Components

React components use PascalCase for both the file name and the exported identifier:

src/components/Header/Header.tsx          → export function Header
@jumbo/components/JumboLayout/index.tsx   → export * from './JumboLayout'

Each component lives in its own folder with index.ts or a file matching the folder name.

Route segments and pages

Next.js route segments use kebab-case:

src/app/[lang]/(common)/dashboards/crypto/page.tsx
src/app/[lang]/(common)/extra-pages/about-us/page.tsx
src/app/[lang]/(solo)/auth/login-1/page.tsx

Demo layout components

Demo-specific components are co-located under src/components/Demo*Layout/:

src/components/Demo1Layout/Header1/Header1.tsx
src/components/Demo1Layout/config/index.ts
src/components/Demo1Layout/themes/index.ts

Utilities and constants

Utility files use camelCase filenames:

@jumbo/utilities/helpers.ts
@jumbo/utilities/formatHelpers.ts
src/utilities/constants/menu-items.ts