Frontend Modular Refactor Plan

Goal

Refactor the frontend source code to be feature-driven, modular, and aligned with cloud-native / 12-factor principles while keeping existing behavior intact.

This plan targets the React app under frontend/src/, reorganizing it into clear feature boundaries and shared utilities.

1) Core Principles

✅ Feature-driven structure

• Organize code by domain/features (chat, nodes, voice, auth, settings, etc.) rather than by type (components, pages, hooks).
• Each feature owns its code (components, hooks, services, pages, styles).

✅ 12-factor / cloud-native alignment

• Configuration from environment variables (process.env.REACT_APP_*) in a central config module.
• No runtime state outside React component/local state.
• Code-splittable and lazy-loadable per feature via route-based splitting.

✅ Non-breaking migration

• Implement refactor incrementally.
• Use re-export wrappers to keep existing import paths intact while transitioning.

2) Target Folder Structure (Recommended)

src/
  app/
    App.js
    routes.js
    index.js
    config.js

  features/
    auth/
      components/
      hooks/
      services/
      pages/
      index.js

    chat/
      components/
      hooks/
      services/
      pages/
      index.js

    nodes/
      components/
      hooks/
      services/
      pages/
      index.js

    voice/
      components/
      hooks/
      services/
      pages/
      index.js

  shared/
    components/
    hooks/
    services/
    utils/
    constants/
    styles/

3) Refactor Roadmap (Feature-by-Feature)

Step 0: Audit & Tag

• Identify large files and cross-feature imports.
• Classify existing files into features.

Step 1: Build Shared Foundations

• Create src/app/config.js for env-based config.
• Move generic services (API, websocket) to src/shared/services.
• Move generic UI primitives (Button, Modal) to src/shared/components.

Step 2: Feature Migration (Example: Chat)

1. Create src/features/chat/ structure.
2. Move ChatWindow, ChatArea, ChatInput, hooks, and related styles into it.
3. Add src/features/chat/index.js to expose exports.
4. Update App.js / routes.js to import from feature exports.
5. Keep old paths stable by adding small wrapper modules during migration.

Step 3: Repeat for other features

• Nodes (src/features/nodes/)
• Voice (src/features/voice/)
• Settings/Profile (src/features/settings/, src/features/profile/)

4) Naming & Convention Rules

• Folder names match feature names exactly.
• File names describe purpose (e.g., ChatPage.js, useChatMessages.js).
• Each feature exports via a single index.js.

5) Testing & Validation

• Run existing unit/integration tests (npm test / yarn test).
• Run npm run build to validate production output.
• Perform manual regression on key flows (chat, node console, voice).

6) Next Step (Optional)

If you want, I can generate a concrete migration plan for one feature (e.g., Chat) including:

• Detailed file mapping (source -> destination)
• Updated import rewrites
• A minimal set of changes per PR (small and reviewable)

Just say which feature you want to start with.