House of Legends Documentation v1.0
plans
2026-05-11
2026 05 11 Project Restructuring Plan

Project Restructuring Plan — 2026-05-11

1. Structure Overview

Current State

MetricValue
Total Files (excluding node_modules, .git, dist)~2,500
Max Nesting Depth6 levels (apps/frontend/raw/ticket-booking/vendor/...)
Build Artifacts (untracked but present)~400MB (out/, .next/, .wrangler/)
Server Backups in Repository2 (convex/, backup/)
Generated Files in Repository3 dirs (convex/_generated/, src/paraglide/, packages/backend/.convex/)
Duplicate Documentation2 plans directories

Key Issues Identified (Prioritized by Impact)

P0 — Critical (Breaks Build/CI)

  1. Server backups (convex/, backup/) tracked in git — 1.4GB+ of non-project files
  2. apps/frontend/out/ (236MB) and tailwindcss-38027.log (11MB) pollute workspace

P1 — High (Maintenance Burden) 3. Generated files tracked (convex/_generated/, src/paraglide/) 4. prd/ and docs/ organization混乱 (project specs + library docs mixed) 5. apps/frontend/docs/superpowers/plans/ duplicates docs/superpowers/plans/

P2 — Medium (Organization) 6. lib/services/ contains mixed concerns (email templates + WhatsApp + PDF generation) 7. hooks/ui/use-chart-tooltip-label.tsx in hooks root instead of proper location 8. docs/lib/paraglide/ and docs/reference/ are library docs, not project docs 9. Large tracked files: homepage.png (2.3MB), llms-full.txt (2MB)

2. Current Tree View

hol/                           # Project root
├── .claude/                   # Project guidelines & rules (~50 files)
├── apps/
│   └── frontend/              # Next.js application
│       ├── app/               # App router pages
│       │   └── [locale]/
│       │       ├── (landing)/ # Public pages
│       │       ├── dashboard/ # Admin dashboard
│       │       └── ...
│       ├── components/        # ~25 component directories
│       ├── hooks/             # React hooks
│       │   ├── ui/           # UI hooks (~12 files)
│       │   ├── admin/
│       │   ├── booking/
│       │   └── use-chart-tooltip-label.tsx  # ← misplaced
│       ├── lib/
│       │   ├── constants/     # ~10 constant files
│       │   ├── utils/        # ~20 utility files
│       │   ├── services/     # Business logic + external integrations
│       │   └── schemas/      # Zod schemas
│       ├── contexts/          # React contexts (3 files)
│       ├── docs/             # DUPLICATE plans directory
│       ├── raw/              # WordPress migration source (READ ONLY)
│       ├── out/              # Build output (236MB!) ← ARTIFACT
│       ├── .next/            # Build cache ← ARTIFACT
│       ├── .wrangler/        # Cloudflare cache ← ARTIFACT
│       └── src/paraglide/    # Generated messages ← ARTIFACT
├── packages/
│   └── backend/               # Convex backend
│       ├── convex/
│       │   ├── domains/       # Business domains (~15 files)
│       │   ├── http/         # HTTP handlers
│       │   └── lib/          # Utilities
│       └── .convex/          # Local Convex data ← ARTIFACT
├── docs/                     # Project docs + library references
│   ├── superpowers/plans/    # Implementation plans (~40 files)
│   ├── lib/paraglide/        # ← LIBRARY DOCS, not project
│   └── reference/            # ← LIBRARY DOCS, not project
├── prd/                      # Feature specs
│   ├── booking-flow/
│   ├── admin-dashboard/
│   └── ...
├── convex/                   # ← SERVER BACKUP (cPanel), NOT Convex!
├── backup/                  # ← SERVER BACKUP, NOT project!
└── [root artifacts]
    ├── homepage.png          # 2.3MB screenshot
    ├── llms-full.txt        # 2MB AI log
    └── aurora-showcase.html  # 27KB reference

Current Directory Depth Analysis

PathDepthIssue
apps/frontend/raw/ticket-booking/vendor/6Excessive nesting for backup files
apps/frontend/app/[locale]/(landing)/experiences/5Route group adds 1 level
packages/backend/convex/lib/onepay/4Acceptable for lib
apps/frontend/components/admin/checkin/4Acceptable for feature components

3. Future State (After Restructure)

Summary of Improvements

MetricBeforeAfterChange
Server backups tracked2 dirs0-100%
Build artifacts in workspace~400MB~0MB-100%
Generated files tracked3 dirs0-100%
Max nesting depth64-33%
Duplicate docs dirs21-1
Large tracked files30-100%

Future Tree View

hol/                           # Project root
├── .claude/                   # Project guidelines & rules
├── apps/
│   └── frontend/              # Next.js application
│       ├── app/               # App router pages
│       ├── components/        # Feature components (flat)
│       ├── hooks/             # React hooks (by feature)
│       ├── lib/
│       │   ├── constants/     # Flat constants
│       │   ├── utils/        # Flat utilities
│       │   └── services/     # Business logic
│       ├── contexts/          # React contexts
│       └── public/            # Static assets
├── packages/
│   └── backend/               # Convex backend
│       └── convex/
│           ├── domains/       # Business domains
│           ├── http/          # HTTP handlers
│           └── lib/          # Utilities
├── docs/                     # Project documentation ONLY
│   ├── superpowers/
│   │   └── plans/            # Single source of truth for plans
│   └── specs/                # Feature specifications (from prd/)
├── scripts/                  # Build & migration scripts
├── .gitignore                # Updated to exclude all artifacts
└── [root config files only]
    ├── package.json
    ├── tsconfig.base.json
    ├── turbo.json
    └── CLAUDE.md

4. Proposed Changes

Category A: Remove Artifacts (P0 — Critical)

A1: Update .gitignore to Exclude Server Backups

Current: convex/ and backup/ at root are tracked

Proposed: Add to .gitignore:

# Server backups (NOT Convex backend)
convex/
backup/

# Generated files
packages/backend/.convex/
packages/backend/convex/_generated/
apps/frontend/src/paraglide/

# Build outputs
apps/frontend/out/
apps/frontend/.next/
apps/frontend/.wrangler/

Rationale: Server backups (1.4GB+) are not part of the project. The actual Convex backend is in packages/backend/.

Impact: Files become untracked but not deleted. User must explicitly remove from git after updating .gitignore.

Priority: P0

A2: Delete Build Artifacts

Current: apps/frontend/out/ (236MB), tailwindcss-38027.log (11MB)

Proposed: Delete these directories:

rm -rf apps/frontend/out/
rm -f apps/frontend/tailwindcss-38027.log

Rationale: These are generated on every build and should never be in the repository.

Impact: Frees ~250MB of workspace space. These are already in .gitignore so not tracked.

Priority: P0

A3: Remove Generated Files from Tracking

Current: convex/_generated/ and src/paraglide/ are tracked

Proposed:

  1. Add patterns to .gitignore
  2. Remove from git tracking (without deleting local files):
git rm --cached -r convex/_generated/
git rm --cached -r apps/frontend/src/paraglide/

Rationale: Generated files should be regenerated, not tracked.

Impact: Convex will regenerate _generated/ on npm run dev. Paraglide will regenerate messages on build.

Priority: P0

Category B: Reorganize Documentation

B1: Consolidate Documentation Structure

Current:

  • docs/ — project docs + library docs (lib/paraglide/, reference/)
  • prd/ — feature specs
  • apps/frontend/docs/ — duplicate plans

Proposed:

docs/
├── superpowers/       # Project-specific docs
│   ├── plans/        # Implementation plans (single source of truth)
│   └── specs/        # Feature specs (moved from prd/)
└── reference/        # Library reference docs (inlined library docs)
    ├── paraglide/    # Paraglide i18n library docs
    └── convex-demos/ # Convex demo references

Rationale: Library docs (docs/lib/paraglide/, docs/reference/) should be clearly separated from project docs. Having prd/ and docs/superpowers/specs/ is confusing.

Impact: Move files, update imports if any.

Priority: P1

B2: Delete Duplicate Plans Directory

Current: apps/frontend/docs/superpowers/plans/ exists

Proposed: Delete apps/frontend/docs/ entirely:

rm -rf apps/frontend/docs/

Rationale: Plans should be in docs/superpowers/plans/ only. The frontend doesn't need its own docs directory.

Impact: Only affects documentation, no code changes.

Priority: P1

Category C: Clean Up Large Tracked Files

C1: Remove Large Reference Files

Current: homepage.png (2.3MB), llms-full.txt (2MB), aurora-showcase.html (27KB)

Proposed: Delete these files:

rm homepage.png llms-full.txt aurora-showcase.html

Rationale: These are reference files, not project source. Screenshots belong in Figma, AI logs are not versioned.

Impact: Frees ~4.3MB. Update git history if needed.

Priority: P1

Category D: Improve Separation of Concerns

D1: Flatten lib/constants/ and lib/utils/

Current:

lib/
├── constants/
│   ├── reservation-status.ts
│   ├── booking-prices.ts
│   └── ...
└── utils/
    ├── date.ts
    ├── price.ts
    └── ...

Proposed: Keep flat structure, but move mislocated files:

  • Move lib/utils/booking-bundle.ts → lib/services/booking-bundle.ts (business logic)
  • Move lib/utils/batch-preview.ts → lib/services/batch.ts (business logic)

Rationale: booking-bundle.ts and batch-preview.ts contain business rules, not pure utilities.

Impact: 2 file moves, update imports.

Priority: P2

D2: Clean Up lib/services/

Current:

lib/services/
├── booking-pricing.ts      # ← looks like a hook
├── email-templates.ts
├── generate-invoice-pdf.tsx
├── qr.ts
├── resend.ts
├── whatsapp.ts
└── zoho.ts

Proposed: Organize as integration modules:

lib/services/
├── email/
│   ├── templates.ts
│   └── resend.ts
├── pdf/
│   └── invoice.tsx
├── qr/
│   ├── token.ts
│   └── canvas.ts
├── whatsapp.ts
└── zoho.ts

Rationale: Grouping related integrations improves discoverability.

Impact: Refactor file structure, update imports.

Priority: P2

D3: Move Misplaced Hook

Current: hooks/use-chart-tooltip-label.tsx in hooks root

Proposed: Move to hooks/ui/:

git mv hooks/use-chart-tooltip-label.tsx hooks/ui/

Rationale: This is a UI hook, should be with other UI hooks.

Impact: 1 file move, update imports.

Priority: P2

Category E: Reduce Nesting

E1: Flatten apps/frontend/raw/ Structure

Current: raw/ticket-booking/ has excessive nesting (vendor/, includes/, etc.)

Proposed: Keep raw/ as-is since it's READ ONLY migration source, but add to .gitignore if not already:

apps/frontend/raw/

Rationale: Raw files are migration reference, not production code. Max nesting acceptable for archive.

Impact: Just ensuring it's ignored.

Priority: P2

5. Migration Plan

Execution Order

Phase 1: Critical Cleanup (Do First)

# 1. Update .gitignore
# Add: convex/ backup/ packages/backend/.convex/ packages/backend/convex/_generated/ apps/frontend/src/paraglide/ apps/frontend/out/
 
# 2. Remove server backups from git tracking (after .gitignore update)
git rm --cached -r convex/
git rm --cached -r backup/
 
# 3. Remove generated files from git tracking
git rm --cached -r packages/backend/convex/_generated/
git rm --cached -r apps/frontend/src/paraglide/
 
# 4. Delete build artifacts
rm -rf apps/frontend/out/
rm -f apps/frontend/tailwindcss-38027.log
 
# 5. Delete large reference files
rm homepage.png llms-full.txt aurora-showcase.html

Phase 2: Documentation Reorganization

# 6. Move prd/specs to docs/superpowers/specs
git mv prd/superpowers/* docs/superpowers/specs/ 2>/dev/null || true
git mv prd/* docs/superpowers/specs/ 2>/dev/null || true
 
# 7. Delete duplicate frontend docs
rm -rf apps/frontend/docs/
 
# 8. Move library docs to docs/reference/
git mv docs/lib docs/reference/inlang 2>/dev/null || true
# Note: docs/reference/ already exists with convex-demos

Phase 3: Code Organization

# 9. Move misplaced hook
git mv hooks/use-chart-tooltip-label.tsx hooks/ui/
 
# 10. Move business logic from utils to services
git mv lib/utils/booking-bundle.ts lib/services/
git mv lib/utils/batch-preview.ts lib/services/batch.ts

Phase 4: Verify & Test

# 11. Verify no unexpected files
git status
 
# 12. Run typecheck
pnpm run typecheck
 
# 13. Run build to verify
pnpm run build

Files to Update After Moves

After Phase 3, update imports in:

  • apps/frontend/lib/services/booking-bundle.ts (if it imports from lib/utils)
  • apps/frontend/lib/services/batch.ts (if it imports from lib/utils)
  • Components using hooks/use-chart-tooltip-label.tsx

Rollback Strategy

If anything breaks:

git reflog
# Find state before restructure
git reset --hard HEAD@{N}

6. Risks & Considerations

RiskMitigation
Removing convex/_generated/ breaks type generationRun pnpm convex dev to regenerate
Removing src/paraglide/ breaks i18nRun pnpm generate to regenerate
Moving docs breaks links in other docsUpdate cross-references after move
Deleting homepage.png breaks Figma referenceUser should keep local copy if needed

7. Expected Benefits

BenefitBeforeAfter
Workspace size (excluding deps)~500MB artifacts~100MB actual project
Git history clarityPolluted with backupsOnly project source
DiscoverabilityLibrary docs mixed with projectClear separation
Build artifactsAlways presentRegenerated on build
Nesting depth6 levels max4 levels max

8. Verification Checklist

After executing changes:

  • git status shows no server backups or generated files
  • pnpm run build succeeds
  • pnpm run typecheck succeeds
  • All imports resolved (no missing modules)
  • Docs in docs/superpowers/plans/ accessible
  • Paraglide i18n works (pnpm generate succeeds)
  • Convex types regenerate (pnpm convex dev)
2026 05 11 Payment Expiry Cron2026 05 11 Realtime Slot Locking