Skip to content

# Folder Structure

An overview of the project directory layout and what each part is responsible for.

## Project Tree

    zenith-dashboard/
    ├── public/                     # Static assets (favicon, images)
    ├── e2e/                        # Playwright end-to-end tests
    │   └── smoke.spec.ts
    ├── src/
    │   ├── app/
    │   │   ├── (auth)/             # Auth pages (standalone layout)
    │   │   │   ├── sign-in/
    │   │   │   ├── sign-up/
    │   │   │   ├── forgot-password/
    │   │   │   ├── reset-password/
    │   │   │   ├── two-factor/
    │   │   │   ├── verify-email/
    │   │   │   └── lock-screen/
    │   │   ├── (dashboard)/        # Dashboard routes (sidebar + header layout)
    │   │   │   ├── analytics/
    │   │   │   ├── billing/
    │   │   │   ├── calendar/
    │   │   │   ├── charts/         # Charts showcase (Radar, Treemap, etc.)
    │   │   │   ├── chat/
    │   │   │   ├── crm/
    │   │   │   ├── customers/
    │   │   │   ├── ecommerce/
    │   │   │   ├── files/
    │   │   │   ├── invoices/
    │   │   │   ├── kanban/
    │   │   │   ├── mail/
    │   │   │   ├── notifications/
    │   │   │   ├── orders/         # CRUD (list, [id], new, [id]/edit)
    │   │   │   ├── pricing/
    │   │   │   ├── products/       # CRUD (list, [id], new, [id]/edit)
    │   │   │   ├── profile/
    │   │   │   ├── saas/
    │   │   │   ├── settings/
    │   │   │   ├── support/
    │   │   │   ├── users/             # User management (CRUD, roles, permissions)
    │   │   │   ├── wizard/
    │   │   │   ├── layout.tsx      # Dashboard shell (sidebar + header)
    │   │   │   └── page.tsx        # Home / overview
    │   │   ├── docs/               # Built-in documentation site
    │   │   ├── fonts/              # Local font files (Geist)
    │   │   ├── globals.css         # Tailwind config + OKLCh color tokens
    │   │   ├── layout.tsx          # Root layout (ThemeProvider, fonts)
    │   │   └── not-found.tsx       # Custom 404 page
    │   ├── components/
    │   │   ├── dashboard/          # Sidebar, Header, Shell, Charts, Customizer
    │   │   │   ├── sidebar.tsx
    │   │   │   ├── sidebar-context.tsx
    │   │   │   ├── header.tsx
    │   │   │   ├── dashboard-shell.tsx
    │   │   │   ├── theme-customizer.tsx
    │   │   │   ├── top-nav.tsx
    │   │   │   └── ...
    │   │   ├── shared/             # DataTable, PageHeader, ConfirmDialog, etc.
    │   │   │   └── data-table/     # TanStack Table components
    │   │   ├── ui/                 # 35+ shadcn/ui primitives (vendored)
    │   │   └── theme-provider.tsx  # Dark/light/system theme context
    │   ├── lib/
    │   │   ├── data/               # Mock data layer with CRUD helpers
    │   │   ├── i18n/              # Internationalization (locale context, messages)
    │   │   ├── navigation.ts       # Dashboard sidebar nav config
    │   │   ├── docs-navigation.ts  # Docs sidebar nav config
    │   │   └── utils.ts            # cn() helper (clsx + tailwind-merge)
    │   └── test/                   # Vitest setup and type declarations
    ├── vitest.config.ts            # Vitest test configuration
    ├── playwright.config.ts        # Playwright E2E configuration
    ├── components.json             # shadcn/ui CLI configuration
    ├── tsconfig.json               # TypeScript configuration
    ├── next.config.ts              # Next.js configuration
    ├── .storybook/                 # Storybook configuration
    ├── seed/                       # Seed/Starter version (clean starting point)
    └── package.json

## Key Directories

### `src/app/(dashboard)/`

All dashboard pages live inside this route group. The parentheses tell Next.js this is a grouping folder — it does not appear in the URL. Every page here automatically inherits the dashboard layout (sidebar, header, and content shell).

### `src/app/(auth)/`

Authentication and utility pages (sign-in, sign-up, forgot password, reset password, two-factor, email verification, lock screen) have their own layout without the dashboard chrome. They use a centered card design.

### `src/app/docs/`

The documentation site (what you are reading now). It lives outside the route groups and has its own dedicated layout with a sidebar navigation.

### `src/components/ui/`

Vendored shadcn/ui components. These are not installed from a package — they are source files you own and can customize freely. Each component uses CVA for variants and the `cn()` utility for class merging.

### `src/components/dashboard/`

Higher-level components that compose the dashboard UI: sidebar, header, theme customizer, top-nav, stats cards, charts, data tables, and activity feeds.

### `src/lib/`

Shared utilities, mock data, and configuration. The `navigation.ts` file defines all sidebar links. The `utils.ts` file exports the `cn()` class-merging function used throughout the project.

### `src/lib/i18n/`

Internationalization infrastructure. Contains locale configuration, a React context provider with localStorage persistence, and JSON message files for English, German, and French.

### `seed/`

A standalone starter project with all infrastructure (theming, i18n, layouts, UI components, Storybook/Vitest configs) but no demo pages or mock data. Copy it to start a new project from scratch.

## Path Aliases

The project uses a single path alias configured in `tsconfig.json`:

    "@/*" → "src/*"

    // Usage:
    import { Button } from "@dashboardpack/core/components/ui/button";
    import type { Metadata } from "next";

    export const metadata: Metadata = {
      title: "Folder Structure",
      description:
        "How the App Router routes, components, and shared core package are organised.",
    };

    import { cn } from "@dashboardpack/core/lib/utils";

All imports throughout the project use this alias instead of relative paths.

## Next Steps

Learn how to customize the look and feel in the Theming guide, or see how to add new pages to the dashboard.