|
| 1 | +# Refactor to Standard Next.js Structure |
| 2 | + |
| 3 | +## 1. Goal |
| 4 | +Simplify the current somewhat over-engineered (FSD/DDD-like) directory structure (`src/domains`, `src/features`, `src/core`, `src/shared`) into a flatter, more standard Next.js application structure. This will reduce cognitive load, make it easier to locate files, and improve maintainability for a personal blog project. |
| 5 | + |
| 6 | +## 2. Scope |
| 7 | +- Reorganize directories inside `src/` to follow a standard Next.js pattern (`app`, `components`, `lib`, `hooks`, `types`). |
| 8 | +- Migrate existing UI components from `src/features/*/ui`, `src/shared/ui`, `src/shared/layout` to `src/components/*`. |
| 9 | +- Migrate business logic, API clients, and utilities from `src/features/*/services`, `src/shared/analytics`, `src/shared/integrations` to `src/lib/*`. |
| 10 | +- Migrate types and models from `src/domains/*/model`, `src/features/*/model` to a top-level `src/types` or colocated with features in `lib`. |
| 11 | +- Migrate configurations and providers from `src/core`, `src/shared/providers` to `src/components/providers` or `src/lib/config`. |
| 12 | +- Update all internal import paths to reflect the new structure. |
| 13 | +- Update `ARCHITECTURE.md` to document the new, simplified structure. |
| 14 | +- Run tests and linters to ensure nothing is broken. |
| 15 | + |
| 16 | +## 3. Constraints |
| 17 | +- The Next.js `app` router structure (`src/app/**`) itself remains mostly unchanged, except for import updates. |
| 18 | +- The `posts/` directory and its content pipeline remain unchanged. |
| 19 | +- The styling approach (Tailwind + CSS variables in `src/styles`) remains unchanged. |
| 20 | +- No new features or bug fixes should be introduced during this refactoring. It is a pure structural change. |
| 21 | + |
| 22 | +## 4. Milestones |
| 23 | +- **Phase 1: Preparation:** |
| 24 | + - Create the new base directories (`src/components`, `src/lib`, `src/types`, `src/hooks`). |
| 25 | +- **Phase 2: Types & Models Migration:** |
| 26 | + - Move files from `src/domains/*/model/*` and `src/features/*/model/*` to `src/types/*` or `src/lib/*`. |
| 27 | + - Fix import paths for these types. |
| 28 | +- **Phase 3: Lib & Utilities Migration:** |
| 29 | + - Move files from `src/features/*/services/*` to `src/lib/content/` (or similar). |
| 30 | + - Move files from `src/shared/integrations/*`, `src/shared/analytics/*`, `src/shared/seo/*` to `src/lib/*`. |
| 31 | + - Move utility functions to `src/lib/utils.ts`. |
| 32 | +- **Phase 4: Component Migration:** |
| 33 | + - Move common UI components from `src/shared/ui/*` to `src/components/ui/`. |
| 34 | + - Move layout components from `src/shared/layout/*` to `src/components/layout/`. |
| 35 | + - Move feature-specific UI from `src/features/*/ui/*` to `src/components/[feature]/`. |
| 36 | + - Move `src/core/providers`, `src/shared/providers` to `src/components/providers/`. |
| 37 | +- **Phase 5: Cleanup & Update Documentation:** |
| 38 | + - Delete empty old directories (`src/domains`, `src/features`, `src/shared`, `src/core`). |
| 39 | + - Update `ARCHITECTURE.md` to reflect the new structure. |
| 40 | +- **Phase 6: Verification:** |
| 41 | + - Run all tests (`npm run test:ci`). |
| 42 | + - Verify local build (`npm run build`). |
| 43 | + |
| 44 | +## 5. Verification |
| 45 | +- All TypeScript compiler checks must pass (`npm run lint`). |
| 46 | +- All unit and E2E tests must pass (`npm run test:ci`). |
| 47 | +- The development server must start without errors (`npm run dev`). |
| 48 | +- A production build must succeed (`npm run build`). |
| 49 | +- The application (both UI and functionality like view counts) must work identically to before. |
| 50 | + |
| 51 | +## 6. Rollback |
| 52 | +- Since the project is managed by Git, if any issues arise or the refactoring becomes too complex, the rollback strategy is to hard reset to the commit prior to starting this execution plan (`git reset --hard HEAD`). |
0 commit comments