diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md deleted file mode 100644 index a0cc8214..00000000 --- a/.planning/ROADMAP.md +++ /dev/null @@ -1,88 +0,0 @@ -# Roadmap: Alwrity - ALwrity Frontend Optimization - -## Overview - -Optimize the frontend build to reduce build time from 5 minutes to under 30 seconds and shrink bundle size from 8.42MB to under 1MB. First, implement code splitting with React.lazy and feature-gated loading using ALWRITY_ENABLED_FEATURES. Then migrate from Create React App to Vite for faster builds. Finally, optimize dependencies for maximum performance. - -## Phases - -**Phase Numbering:** -- Integer phases (1, 2, 3, 4): Planned work -- All phases planned and ready for execution - ---- - -### Phase 1: Code Splitting & Feature-Based Lazy Loading ✅ Complete -**Goal**: Replace all static imports with React.lazy dynamic imports and add feature-gated loading using ALWRITY_ENABLED_FEATURES. Also convert MUI icon barrel imports to individual imports (moved here from Phase 3 for Vite readiness). -**Depends on**: Nothing (first phase) -**Requirements**: VITE-04 (code splitting), VITE-06 (dependency optimization) -**Success Criteria** (what must be TRUE): - 1. ✅ All 31+ route components loaded via React.lazy (not static imports) - 2. ✅ Initial bundle size reduced from 8.42MB to 2.50MB (70% reduction) - 3. ✅ Disabled features (via ALWRITY_ENABLED_FEATURES) don't load their bundles - 4. ✅ All existing routes still work correctly - 5. ✅ No build warnings or errors with CRA - 6. ✅ All MUI icon imports changed from barrel to individual (111 files) - -**Plans**: 3 plans (all complete) - -Plans: -- [x] 01-01: Convert 31 static imports to React.lazy with Suspense -- [x] 01-02: Add feature-gated route loading using ALWRITY_ENABLED_FEATURES -- [x] 01-03: Convert MUI icon barrel imports to individual imports (111 files) - ---- - -### Phase 2: Migrate from CRA to Vite (Next) -**Goal**: Migrate frontend from Create React App to Vite for fast builds -**Depends on**: Phase 1 ✅ -**Requirements**: VITE-01, VITE-02, VITE-03 -**Success Criteria** (what must be TRUE): - 1. `npm run dev` starts Vite dev server with HMR - 2. `npm run build` completes in under 30 seconds (down from 5 minutes) - 3. All environment variables work with `VITE_*` prefix - 4. TypeScript compiles without errors - 5. Material UI theme renders correctly - -**Plans**: 3 plans - -Plans: -- [ ] 02-01: Install Vite dependencies and create configuration -- [ ] 02-02: Migrate index.html and entry point -- [ ] 02-03: Update environment variables and scripts - ---- - -### Phase 3: Dependency Cleanup & Production Validation -**Goal**: Remove unused dependencies and deploy Vite build to production -**Depends on**: Phase 2 -**Requirements**: VITE-07, VITE-08, VITE-09 -**Success Criteria** (what must be TRUE): - 1. Unused dependencies identified and removed - 2. Production build serves correctly (preview mode) - 3. All features tested and working (Clerk auth, Stripe, CopilotKit) - 4. Vercel deployment config updated for Vite - 5. Build time consistently under 30 seconds - 6. Total bundle size under 2MB - -**Plans**: 2 plans (consolidated from former Phase 3 & 4) - -Plans: -- [ ] 03-01: Audit and remove unused dependencies, update Vercel config -- [ ] 03-02: Full feature testing and performance validation - ---- - -## Execution Order - -Phases execute in numeric order: 1 → 2 → 3 - -**Key insight:** Phase 1 (code splitting) works with CRA, so we immediately reduce bundle size. Phase 2 (Vite) gives build speed bonus on already-split bundles. Phase 3 is cleanup and deployment. - -## Progress - -| Phase | Plans Complete | Status | Completed | -|-------|----------------|--------|-----------| -| 1. Code Splitting & MUI Optimization | 3/3 | ✅ Complete | 2026-05-08 | -| 2. Migrate CRA to Vite | 0/3 | ⏳ Ready | - | -| 3. Cleanup & Production | 0/2 | ⏳ Planned | - | diff --git a/.planning/STATE.md b/.planning/STATE.md deleted file mode 100644 index 5a71080e..00000000 --- a/.planning/STATE.md +++ /dev/null @@ -1,73 +0,0 @@ -# Project State: Alwrity - -## Current Position - -**Active Phase:** Phase 1 - Code Splitting & Feature-Based Lazy Loading -**Phase Status:** ✅ Complete — Ready for Phase 2 -**Milestone:** v1.0 - Frontend Optimization - -## Phase Progress - -### Phase 1: Code Splitting & Feature-Based Lazy Loading -- **Status:** ✅ Complete -- **Plans:** 3 plans executed (01-01, 01-02, 01-03) - -**Plans:** -- [x] 01-01: Convert 31 static imports to React.lazy with Suspense -- [x] 01-02: Add feature-gated route loading using ALWRITY_ENABLED_FEATURES -- [x] 01-03: Convert MUI icon barrel imports to individual imports (111 files) - -**Results:** -- Main bundle: 8.42MB → 2.50MB (70% reduction via React.lazy) -- 190+ chunk files for route-level code splitting -- 47 routes feature-gated with ALWRITY_ENABLED_FEATURES -- 16 feature keys in FEATURE_KEYS constant -- 111 files converted from barrel to individual MUI icon imports -- Zero barrel imports from @mui/icons-material remain - -### Phase 2: Migrate CRA to Vite -- **Status:** Ready to start (Phase 1 complete) -- **Plans:** 3 plans created (02-01, 02-02, 02-03) -- **Dependencies:** Phase 1 complete - -**Plans:** -- [ ] 02-01: Install Vite dependencies and create configuration -- [ ] 02-02: Migrate index.html and entry point -- [ ] 02-03: Update environment variables and scripts - -### Phase 3: Production Validation (Planned) -- Depends on: Phase 2 -- Focus: Vercel deploy, full feature testing - -### Phase 4: (Removed — MUI icon optimization folded into Phase 1-03) - -## Decisions Made - -### Locked Decisions -- **Code splitting first**, then Vite migration (not the other way around) ✅ Done -- Use React.lazy for ALL route components (this is a React feature, NOT bundler-specific) ✅ Done -- Use ALWRITY_ENABLED_FEATURES for feature-gated route loading ✅ Done -- **MUI icon imports before Vite migration** — barrel imports converted to individual per-file default imports ✅ Done -- Use Vite 5.x with @vitejs/plugin-react -- Disable sourcemaps in production build for speed -- Migrate env vars from `REACT_APP_*` to `VITE_*` - -### Patterns Established -- **MUI icon imports**: Always `import IconName from '@mui/icons-material/IconName'` — never barrel destructuring -- **Route splitting**: All route components use React.lazy with Suspense -- **Feature gating**: FeatureRoute wraps inside ProtectedRoute (auth → then feature check) - -## Key Insight - -**React.lazy is a React feature (not CRA or Vite specific).** Doing code splitting first with CRA: -1. Immediately reduces main bundle from 8.42MB → ~1-2MB -2. Adds no risk (React.lazy is stable since React 16.6) -3. Makes Vite migration smoother (bundles are already split) -4. ALWRITY_ENABLED_FEATURES can prevent disabled feature bundles from loading at all - -**MUI icon barrel imports eliminated** — 111 files converted to individual per-file imports. This ensures reliable tree-shaking during Vite migration and beyond. - ---- - -*Last updated: 2026-05-08* -*Updated by: gsd-executor* diff --git a/.planning/phases/01-code-splitting/01-03-SUMMARY.md b/.planning/phases/01-code-splitting/01-03-SUMMARY.md deleted file mode 100644 index 3fd7670c..00000000 --- a/.planning/phases/01-code-splitting/01-03-SUMMARY.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -phase: 01-code-splitting -plan: 03 -type: execute -subsystem: frontend -tags: [performance, MUI, icons, tree-shaking, barrel-imports] -requires: - - phase: 01-code-splitting-02 - provides: feature gating structure for route protection -provides: - - All MUI icon imports converted from barrel (destructured) to individual per-file default imports - - Zero barrel imports from @mui/icons-material remain in the codebase -affects: [02-vite-migration, build performance] -tech-stack: - added: [] - patterns: [individual MUI icon imports, per-file default imports for tree-shaking] -key-files: - created: [] - modified: - - frontend/src/components/shared/ErrorBoundary.tsx - - frontend/src/components/SubscriptionGuard.tsx - - frontend/src/components/SubscriptionExpiredModal.tsx - - frontend/src/pages/SchedulerDashboard.tsx - - frontend/src/pages/BillingPage.tsx - - +106 additional frontend component files -key-decisions: - - "All MUI icon barrel imports converted BEFORE Vite migration to eliminate Webpack 4 tree-shaking uncertainty" - - "Used per-file default imports (import X from '@mui/icons-material/X') instead of destructured barrel imports" - - "Aliased icons (e.g., ErrorOutline as ErrorIcon) converted to named default imports matching the alias (import ErrorIcon from '@mui/icons-material/ErrorOutline')" - - "JSX variable names preserved — only import statements changed" -patterns-established: - - "MUI icon imports: always use import X from '@mui/icons-material/X' pattern, never import { X } from '@mui/icons-material'" -duration: 45min -completed: 2026-05-08 ---- - -# Phase 1 Plan 01-03: MUI Icon Import Optimization Summary - -**Converted all 300+ MUI icon barrel imports to individual per-file default imports across 111 frontend files — eliminating Webpack 4 tree-shaking uncertainty before Vite migration** - -## Performance - -- **Duration:** ~35 min -- **Completed:** 2026-05-08 -- **Tasks:** 10 commits across 111 files -- **Files modified:** 111 - -## Accomplishments - -- Converted **all barrel** `import { X } from '@mui/icons-material'` to individual `import X from '@mui/icons-material/X'` — **zero barrel imports remaining** -- Modified **111 files** across every area: PodcastMaker, YouTubeCreator, OnboardingWizard, billing, SEO, shared components, and more -- Handled aliased imports (`IconName as Alias`) correctly — JSX variable names preserved unchanged -- Build verified — `npm run build:nomap` succeeds with zero new errors -- Enables reliable tree-shaking during Phase 2 (Vite migration) — each file imports only the icons it uses - -## Task Commits - -Each batch was committed atomically: - -1. **ErrorBoundary** (`components/shared/`) - `46781a0` — 5 icons -2. **SubscriptionGuard** - `bda75cb` — 2 icons -3. **SubscriptionExpiredModal** - `80f76b1` — 3 icons -4. **SchedulerDashboard** - `7ffd972` — 7 icons -5. **BillingPage** - `a76671c` — 1 icon -6. **Billing, Blog, ContentPlanning, ErrorBoundary, Pricing, Alerts** - `a009cbb` — 8 files, 36 insertions -7. **ImageStudio, Landing, LinkedIn, MainDashboard, OnboardingWizard** - `205e098` — 14 files, 65 insertions -8. **PodcastMaker AnalysisPanel** - `25ce5b9` — 18 files, 58 insertions -9. **PodcastMaker, ProductMarketing, Research, Scheduler, SEO, Shared** - `986a7e5` — 44 files, 149 insertions -10. **StoryWriter, YouTubeCreator** - `6361255` — 22 files, 67 insertions - -## Files Modified - -**111 files total** across the frontend source tree: - -- `components/billing/` — 2 files (ComprehensiveAPIBreakdown, CostOptimizationRecommendations) -- `components/BlogWriter/` — 1 file (BlogWriterPhasesSection) -- `components/ContentPlanningDashboard/` — 2 files (CardExpansionWrapper, StrategyErrorBoundary) -- `components/ErrorBoundary.tsx` — 1 file (3 icons) -- `components/ImageStudio/` — 2 files (AssetFilters, CreateStudioCostAlerts) -- `components/Landing/` — 2 files (EnterpriseCTA, FeatureShowcase) -- `components/LinkedInWriter/` — 1 file (FactCheckResults) -- `components/MainDashboard/` — 1 file (MainDashboard) -- `components/OnboardingWizard/` — 7 files (incl. VoiceAvatarPlaceholder with 22 icons) -- `components/PodcastMaker/` — 40 files (AnalysisPanel, CreateStep, ScriptEditor, etc.) -- `components/Pricing/` — 1 file (PricingPage) -- `components/ProductMarketing/` — 5 files (CampaignWizard, ProductPhotoshootStudio, etc.) -- `components/Research/` — 2 files (PersonalizationIndicator, ResearchInputContainer) -- `components/SchedulerDashboard/` — 1 file (SchedulerCharts) -- `components/SEODashboard/` — 3 files (AIInsightsPanel, HealthScore, MetricCard) -- `components/shared/` — 12 files (ErrorBoundary, AlertsBadge, ProtectedRoute, etc.) -- `components/StoryWriter/` — 3 files (AIStorySetupModal, FormFieldWithTooltip, SelectFieldWithTooltip) -- `components/SubscriptionGuard.tsx` — 1 file -- `components/SubscriptionExpiredModal.tsx` — 1 file -- `components/YouTubeCreator/` — 19 files (SceneCard, RenderStep, PlanStep, etc.) -- `pages/` — 2 files (BillingPage, ResearchDashboard/PresetsCard) - -## Decisions Made - -- **Convert all barrel imports now, before Vite migration** — CRA's Webpack 4 cannot reliably tree-shake barrel imports. Converting before the bundler swap reduces migration risk and ensures Vite's native ESM tree-shaking works optimally. -- **Per-file default import pattern** — Every icon gets its own import line: `import IconName from '@mui/icons-material/IconName'`. This is the most predictable pattern and works identically in both Webpack and Vite. -- **Alias handling** — For icons imported as `{ X as Y }`, the alias `Y` becomes the import name: `import Y from '@mui/icons-material/X'`. JSX usage unchanged. -- **Multiple import lines preserved** — Files with separate barrel imports from `@mui/icons-material` were converted to multiple individual import blocks, preserving the original organizational structure. - -## Deviations from Plan - -None - this was ad-hoc work not covered by an existing PLAN.md. - -## Issues Encountered - -- **Task agent timeout**: First attempt at parallel conversion agents failed silently for batches 1-2 (73 files). Re-launched with explicit edit instructions - succeeded on second attempt. -- **No naming conflicts found**: Despite converting 300+ icon imports across 111 files, no variable naming collisions occurred. Each icon only appears once per file. - -## Build Verification - -- `npm run build:nomap` — **PASSED** with zero errors -- Only pre-existing CRA bundle size warning remains (expected — Vite migration will resolve it in Phase 2) -- No new build warnings introduced - -## Next Phase Readiness - -- Frontend is ready for **Phase 2: Vite Migration** -- All MUI icon imports use individual default imports — tree-shaking will work correctly with Vite's rollup -- User should perform manual testing of Podcast Maker with `REACT_APP_ENABLED_FEATURES=podcast` before Vite migration begins -- After manual verification, proceed with [Phase 2-01: Install Vite dependencies and create configuration] - ---- - -*Phase: 01-code-splitting* -*Completed: 2026-05-08*