# 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.
