02 - Project Structure

Overview

The wavic-webapp follows Next.js 15 conventions with a well-organized structure optimized for scalability and maintainability.

Root Directory

wavic-webapp/
├── .npmrc                 # npm config (legacy-peer-deps)
├── eslint.config.mjs      # ESLint 9 flat configuration
├── .husky/                # Git hooks (pre-commit)
├── .prettierignore        # Prettier ignore patterns
├── .vscode/               # VS Code settings
├── lint-staged.config.mjs # Lint-staged configuration
├── next.config.mjs        # Next.js configuration
├── package.json           # Dependencies and scripts
├── postcss.config.cjs     # PostCSS configuration (@tailwindcss/postcss)
├── prettier.config.mjs    # Prettier configuration
├── tsconfig.json          # TypeScript configuration
├── public/                # Static assets
├── src/                   # Application source code
└── types/                 # Global TypeScript types

Note: Tailwind CSS v4 uses CSS-first configuration. All theme, plugins, and custom variants are defined in src/app/globals.css using @theme inline, @plugin, and @custom-variant directives. There is no tailwind.config.ts.

Source Directory (src/)

App Directory (Next.js App Router)

src/app/
├── layout.tsx             # Root layout (providers, global styles)
├── not-found.tsx          # 404 page
├── fonts.ts               # Font configuration
├── globals.css            # Global CSS
├── wave.css               # Waveform-specific styles
├── waveform.css           # Additional waveform styles
│
├── (hydrogen)/            # Main authenticated routes (route group)
│   ├── layout.tsx         # Multi-layout switcher
│   ├── page.tsx           # Home/dashboard page
│   │
│   ├── artist/            # Artist space routes
│   │   └── [artistId]/    # Dynamic artist route
│   │       └── page.tsx
│   │
│   ├── project/           # Project routes
│   │   └── [projectId]/   # Dynamic project route
│   │       └── page.tsx
│   │
│   ├── wave/              # Track/waveform routes
│   ├── library/           # Music library
│   ├── onboarding/        # User onboarding
│   ├── profile/           # User profile
│   ├── search/            # Search pages
│   ├── storage/           # Storage management
│   ├── transfers/         # Shared files
│   ├── trash/             # Deleted items
│   └── user/              # User settings
│
├── (other-pages)/         # Secondary routes
│
├── api/                   # API routes
│   └── auth/              # NextAuth API
│       └── [...nextauth]/
│
├── auth/                  # Auth pages (non-protected)
├── signin/                # Sign in page
├── reset-password/        # Password reset
│
└── shared/                # Shared page components
    ├── artist/            # Artist page logic
    ├── project/           # Project page logic
    ├── track-player/      # Audio player
    ├── wave/              # Waveform components
    ├── modal-views/       # Modal management
    ├── drawer-views/      # Drawer management
    └── ...

Components Directory

src/components/
├── MainComponent.tsx      # Main app wrapper
├── next-progress.tsx      # Page loading progress
│
├── ui/                    # Base UI components
│   ├── form.tsx           # Form components
│   ├── table.tsx          # Table component
│   ├── select.tsx         # Select dropdown
│   ├── datepicker.tsx     # Date picker
│   ├── pagination.tsx     # Pagination
│   ├── breadcrumb.tsx     # Breadcrumb navigation
│   ├── skeleton.tsx       # Loading skeletons
│   ├── Track-player.tsx   # Audio track player
│   ├── Volume-controller.tsx
│   └── ...
│
├── cards/                 # Card components
├── charts/                # Chart components (Recharts)
├── control/               # Control elements
├── headers/               # Page headers
│   ├── artist-header.tsx
│   └── new-project-header.tsx
│
├── icons/                 # Icon components
├── loader/                # Loading indicators
├── modal/                 # Modal dialogs
│   ├── share-modal.tsx
│   ├── new-project-selection-modal.tsx
│   └── upgrade-popup-storage.tsx
│
├── skeletons/             # Loading skeletons
│   ├── header-skeleton.tsx
│   └── project-skeleton.tsx
│
├── tables/                # Table implementations
├── banners/               # Banner components
├── button/                # Button variants
├── dnd-sortable/          # Drag-and-drop
├── drop-downs/            # Dropdown menus
├── search/                # Search components
├── settings/              # Settings components
└── ...

Server Actions Directory

src/server-actions/
├── artist/
│   └── actions.tsx        # Artist CRUD operations
├── project/
│   └── actions.tsx        # Project CRUD operations
├── track/
│   └── actions.tsx        # Track CRUD operations
├── subscription/
│   └── actions.tsx        # Billing operations
├── shareWithUser.ts       # Sharing functionality
└── zip-folders.ts         # Download as ZIP

Contexts Directory

src/contexts/
├── waveContext.tsx           # Audio/waveform state
├── notificationContext.tsx   # Notifications
├── drop-zone-context.tsx     # File upload state
├── loading-context.tsx       # Global loading
├── navigatorContext.tsx      # Navigation state
├── audioplayer-table-context.tsx
├── fileContext.js            # File management
├── recentTracksContext.tsx   # Recent tracks
└── globalFileDropZone.tsx    # Global dropzone

Hooks Directory

src/hooks/
├── use-layout.ts             # Layout selection
├── use-media.ts              # Media queries
├── use-window-size.ts        # Window dimensions
├── use-is-mounted.ts         # Mount detection
├── use-click-away.ts         # Outside click
├── use-copy-to-clipboard.ts  # Clipboard
├── use-local-storage.ts      # Local storage
├── use-column.ts             # Table columns
├── use-table.ts              # Table functionality
├── use-filter-control.ts     # Filtering
├── use-countdown.ts          # Countdown timer
├── use-update-session.ts     # Session refresh
└── ... (30+ hooks)

Layouts Directory

src/layouts/
├── beryllium/                # Default layout
│   ├── beryllium-layout.tsx
│   ├── beryllium-header.tsx
│   └── beryllium-utils.ts
│
├── hydrogen/                 # Hydrogen layout
│   └── layout.tsx
│
├── helium/                   # Helium layout
│   └── helium-layout.tsx
│
├── lithium/                  # Lithium layout
│   └── lithium-layout.tsx
│
├── boron/                    # Boron layout
│   └── boron-layout.tsx
│
├── carbon/                   # Carbon layout
│   └── carbon-layout.tsx
│
├── nav-menu/                 # Navigation components
├── profile-menu.tsx          # Profile dropdown
├── notification-dropdown.tsx
├── messages-dropdown.tsx
├── sticky-header.tsx
└── header-menu-right.tsx

Config Directory

src/config/
├── site.config.tsx        # Site metadata
├── routes.ts              # Route definitions
├── constants.ts           # App constants
├── enums.ts               # Enumerations
├── color-presets.ts       # Theme colors
├── mail.ts                # Email templates
└── messages.ts            # UI messages

Lib Directory

src/lib/
├── access/                # Access control utilities
│   └── index.ts
└── collaborators/         # Collaborator utilities
    └── index.ts

Utils Directory

src/utils/
└── class-names.ts         # Tailwind class merging (cn)

Store Directory

src/store/
├── checkout.ts            # Checkout state (Jotai)
└── quick-cart/            # Cart state

Data Directory (Mock/Static Data)

src/data/
├── icons-data.ts          # Icon definitions
├── billing-history.ts     # Billing mock data
├── members-data.ts        # Team members
├── notifications.ts       # Notification samples
├── forms/                 # Form schemas
└── ...                    # Other static data

Types Directory (Global Types)

types/
├── artist.ts              # TArtist, TProject, TCollaborator
├── track.ts               # TTrack, TFile
├── user.ts                # IUser
├── status.ts              # Status enums
├── billing.ts             # Billing types
├── notification.interface.ts
├── search-items.ts        # Search result types
├── trash.ts               # Trash types
├── next-auth.d.ts         # NextAuth type extensions
├── react-table.d.ts       # React Table extensions
└── reset.d.ts             # ts-reset types

Public Directory

public/
├── logo.png               # Main logo
├── logo-short.svg         # Icon logo
├── env2.hdr               # HDR environment map (3D)
│
├── auth/                  # Auth page images
├── beta/                  # Beta feature images
├── default/               # Default avatars
├── Features/              # Feature images
├── fonts/                 # Web fonts
├── onboarding/            # Onboarding assets
└── onboarding-bg/         # Background images

File Naming Conventions

Type	Convention	Example
Pages	page.tsx	artist/[artistId]/page.tsx
Layouts	layout.tsx	(hydrogen)/layout.tsx
Components	kebab-case.tsx	track-player.tsx
Hooks	use-name.ts	use-window-size.ts
Types	PascalCase	TArtist, IUser
Server Actions	actions.tsx	artist/actions.tsx
Contexts	nameContext.tsx	waveContext.tsx
Config	name.config.ts	site.config.tsx

Import Aliases

The project uses TypeScript path aliases (configured in tsconfig.json):

import { Button } from '@/components/ui'; // src/components/ui
import { routes } from '@/config/routes'; // src/config
import { useMedia } from '@/hooks/use-media'; // src/hooks
import { TArtist } from 'types/artist'; // types/
import cn from '@/utils/class-names'; // src/utils