Frontend Restructuring Plan — 2026-05-10

1. Structure Overview

Current State

Total directories (excluding node_modules/.git): ~90+
Max nesting depth: 5 levels (components/features/forms/proposal-form-components/)
Key issues: Over-nested components/features/, misplaced lib/ files, duplicate components/ vs components/features/

Target State

Max nesting depth: 3 levels (app routes)
Flat components/: No nested subdirs except ui/ variants
Organized lib/: All files in proper subdirectories

2. Current Tree View (Key Problem Areas)

apps/frontend/
├── app/                              # Routes — OK (3 levels max)
│   ├── [locale]/
│   │   ├── (landing)/               # Route group
│   │   │   ├── about/
│   │   │   ├── artists/
│   │   │   ├── booking/
│   │   │   ├── contact/
│   │   │   ├── experiences/
│   │   │   ├── legal/
│   │   │   ├── reviews/
│   │   │   ├── schedule/
│   │   │   ├── venues/
│   │   │   └── wall/
│   │   ├── audience/                # Outside route group
│   │   └── design-system/           # Outside route group
│   └── dashboard/
│       ├── admin/
│       ├── checkin/
│       ├── experiences/
│       └── reservations/
│
├── components/                       # ⚠ PROBLEMS HERE
│   ├── admin/                        # Admin components
│   ├── artists/
│   ├── booking/
│   ├── confirmation/
│   ├── experiences/
│   ├── features/                     # ❌ DEEPLY NESTED (4-5 levels)
│   │   ├── admin/                   # DUPLICATE of components/admin/
│   │   ├── booking/                 # DUPLICATE of components/booking/
│   │   ├── dinner-theater/          # DUPLICATE of components/experiences/
│   │   ├── experiences/             # DUPLICATE
│   │   ├── forms/                   # 4 levels
│   │   │   └── proposal-form-components/ # 5 levels!
│   │   ├── french-mentalist/        # 4 levels
│   │   ├── sections/                # 4 levels
│   │   │   └── accordions/          # 5 levels!
│   │   └── ui/                      # DUPLICATE of components/ui/
│   ├── home/
│   ├── layout/
│   ├── menu/
│   ├── minigames/
│   ├── pos/
│   ├── profile/
│   ├── shows/
│   ├── table/
│   ├── ui/
│   │   ├── aurora/                  # OK — specialized
│   │   └── design-system/           # OK — specialized
│   ├── venues/
│   └── wall/
│
├── lib/                              # ⚠ MISPLACED FILES
│   ├── constants/                   # OK
│   ├── convex/                      # OK
│   ├── data/                        # OK
│   ├── nuqs/                        # OK
│   ├── schemas/                     # OK
│   ├── services/                    # OK
│   ├── templates/                   # OK
│   ├── utils/                       # OK
│   ├── booking-pricing.ts           # ❌ Should be lib/services/
│   ├── chart-utils.ts              # ❌ Should be lib/utils/
│   ├── countries.ts                # ❌ Should be lib/data/
│   ├── email-templates.ts          # ❌ Should be lib/services/
│   ├── escape.ts                   # ❌ Should be lib/utils/
│   ├── generate-invoice-pdf.tsx    # ❌ Should be lib/services/
│   ├── qr-token.ts                 # ❌ Should be lib/services/
│   ├── qr.ts                       # ❌ Should be lib/services/
│   ├── resend.ts                   # ❌ Should be lib/services/
│   ├── utils.ts                    # ❌ Should be lib/utils/
│   ├── whatsapp.ts                 # ❌ Should be lib/services/
│   └── zoho.ts                     # ❌ Should be lib/services/
│
├── hooks/                           # ✅ JUST CREATED
├── contexts/                        # ✅ JUST CREATED
├── providers/                      # ✅ EMPTY - ready

3. Future Tree View (After Restructure)

apps/frontend/
├── app/
│   ├── [locale]/
│   │   ├── (marketing)/             # Renamed from (landing)
│   │   │   ├── about/
│   │   │   ├── artists/
│   │   │   ├── booking/
│   │   │   ├── contact/
│   │   │   ├── experiences/
│   │   │   │   ├── creative-workshop/
│   │   │   │   ├── dinner-theater/
│   │   │   │   ├── french-mentalist/
│   │   │   │   ├── our-evening/
│   │   │   │   └── private-events/
│   │   │   ├── legal/
│   │   │   │   ├── complaint/
│   │   │   │   ├── consumer-protection/
│   │   │   │   ├── dispute-resolution/
│   │   │   │   ├── payment-policy/
│   │   │   │   ├── privacy-policy/
│   │   │   │   ├── return-policy/
│   │   │   │   ├── shipping-policy/
│   │   │   │   └── terms-of-use/
│   │   │   ├── reviews/
│   │   │   ├── schedule/
│   │   │   ├── venues/
│   │   │   └── wall/
│   │   ├── audience/
│   │   └── design-system/
│   └── dashboard/
│       ├── admin/
│       │   └── pos/challenges/
│       ├── checkin/
│       ├── experiences/
│       └── reservations/
│
├── components/
│   ├── ui/                         # Base shadcn/ui components
│   │   ├── aurora/
│   │   └── design-system/
│   ├── admin/                      # Flat — no subdirs
│   ├── artists/
│   ├── booking/
│   ├── experiences/
│   │   ├── french-mentalist/       # Keep deep — self-contained feature
│   │   └── dinner-theater/
│   ├── confirmation/
│   ├── home/
│   ├── layout/
│   ├── marketing/                  # Renamed from features/sections
│   │   └── accordions/
│   ├── menu/
│   ├── minigames/
│   ├── pos/
│   ├── profile/
│   ├── shows/
│   ├── table/
│   ├── venues/
│   └── wall/
│
├── lib/
│   ├── hooks/                      # ✅ Already done
│   ├── contexts/                   # ✅ Already done
│   ├── constants/
│   ├── convex/
│   ├── data/
│   │   └── countries.ts            # Moved from root
│   ├── schemas/
│   ├── services/
│   │   ├── booking-pricing.ts     # Moved from root
│   │   ├── email-templates.ts     # Moved from root
│   │   ├── generate-invoice-pdf.tsx # Moved from root
│   │   ├── qr.ts                  # Moved from root
│   │   ├── qr-token.ts            # Moved from root
│   │   ├── resend.ts              # Moved from root
│   │   ├── whatsapp.ts            # Moved from root
│   │   └── zoho.ts                # Moved from root
│   ├── templates/
│   └── utils/
│       ├── chart-utils.ts         # Moved from root
│       ├── escape.ts              # Moved from root
│       └── utils.ts               # Moved from root
│
├── hooks/                          # ✅ Already done
├── contexts/                       # ✅ Already done
├── providers/                      # ✅ Empty — ready for future

4. Proposed Changes

A. Flatten `components/features/` — HIGH PRIORITY

Problem: components/features/ has 4-5 levels of nesting and duplicates components/ structure.

Current	Proposed
`components/features/admin/*`	`components/admin/*`
`components/features/booking/*`	`components/booking/*`
`components/features/experiences/*`	`components/experiences/*`
`components/features/dinner-theater/*`	`components/experiences/dinner-theater/*`
`components/features/french-mentalist/*`	`components/experiences/french-mentalist/*`
`components/features/sections/*`	`components/marketing/*`
`components/features/sections/accordions/*`	`components/marketing/accordions/*`
`components/features/forms/*`	`components/forms/*` (NEW)
`components/features/forms/proposal-form-components/*`	`components/forms/proposal-form-components/*`
`components/features/ui/*`	`components/ui/*` (merge)

Rationale: features/ was likely created to separate "feature" components from "page" components, but it creates unnecessary depth without benefit. Components should be organized by domain, not by "feature" vs "page".

Impact: 60+ files moved. All imports need updating.

B. Move misplaced `lib/` files — MEDIUM PRIORITY

Current	Proposed
`lib/booking-pricing.ts`	`lib/services/booking-pricing.ts`
`lib/chart-utils.ts`	`lib/utils/chart-utils.ts`
`lib/countries.ts`	`lib/data/countries.ts`
`lib/email-templates.ts`	`lib/services/email-templates.ts`
`lib/escape.ts`	`lib/utils/escape.ts`
`lib/generate-invoice-pdf.tsx`	`lib/services/generate-invoice-pdf.tsx`
`lib/qr.ts`	`lib/services/qr.ts`
`lib/qr-token.ts`	`lib/services/qr-token.ts`
`lib/resend.ts`	`lib/services/resend.ts`
`lib/utils.ts`	`lib/utils/utils.ts`
`lib/whatsapp.ts`	`lib/services/whatsapp.ts`
`lib/zoho.ts`	`lib/services/zoho.ts`

Rationale: KISS — files should be in their logical subdirectory, not floating in lib/ root.

Impact: 12 files moved. Import updates needed.

C. Create `components/forms/` for proposal forms — LOW PRIORITY

Current	Proposed
`components/features/forms/*`	`components/forms/*`
`components/features/forms/proposal-form-components/*`	`components/forms/proposal-form-components/*`

Rationale: Forms are a distinct concern. Keep them flat within components/forms/.

D. Rename `(landing)` route group to `(marketing)` — LOW PRIORITY

Current	Proposed
`app/[locale]/(landing)/`	`app/[locale]/(marketing)/`

Rationale: (landing) implies landing page only. (marketing) better describes all pages in this group: about, artists, experiences, venues, etc.

5. Migration Plan

Step 1: Move `lib/` misplaced files

git mv lib/booking-pricing.ts lib/services/
git mv lib/chart-utils.ts lib/utils/
git mv lib/countries.ts lib/data/
git mv lib/email-templates.ts lib/services/
git mv lib/escape.ts lib/utils/
git mv lib/generate-invoice-pdf.tsx lib/services/
git mv lib/qr.ts lib/services/
git mv lib/qr-token.ts lib/services/
git mv lib/resend.ts lib/services/
git mv lib/utils.ts lib/utils/
git mv lib/whatsapp.ts lib/services/
git mv lib/zoho.ts lib/services/

Then update imports: find . -type f \( -name "*.tsx" -o -name "*.ts" \) | xargs sed -i 's|lib/booking-pricing|lib/services/booking-pricing|g' (repeat for each file).

Step 2: Flatten `components/features/`

# Move feature components to their logical locations
git mv components/features/admin/* components/admin/
git mv components/features/booking/* components/booking/
git mv components/features/experiences/* components/experiences/
git mv components/features/dinner-theater/* components/experiences/dinner-theater/
git mv components/features/french-mentalist/* components/experiences/french-mentalist/
git mv components/features/sections/* components/marketing/
git mv components/features/sections/accordions/* components/marketing/accordions/
git mv components/features/forms/* components/forms/
git mv components/features/forms/proposal-form-components/* components/forms/proposal-form-components/
git mv components/features/ui/* components/ui/
 
# Remove empty features directory
rmdir components/features

Step 3: Update all imports

find . -type f \( -name "*.tsx" -o -name "*.ts" \) | xargs sed -i 's|components/features/|components/|g'

Step 4: Rename `(landing)` to `(marketing)`

git mv "app/[locale]/(landing)" "app/[locale]/(marketing)"

Step 5: Verify

pnpm build
pnpm typecheck

6. Risks & Considerations

Breaking imports: 60+ files have imports from ~/components/features/ — all must be updated
Git history: Using git mv preserves history but the diff will be large
CI/CD: May need to update path filters if configured
Documentation: CLAUDE.md and DESIGN.md reference paths that will change

7. Expected Benefits

Nesting reduced: From 5 levels to 3 levels max
Discoverability: Components organized by domain, not by "feature" vs "page"
Simplicity: components/ flat structure, deep nesting only where justified (experiences/french-mentalist is a self-contained feature)
Consistency: lib/ now has only directories, no floating files

2026 05 10 Experiences Page Fix 2026 05 10 Hooks Migration