khata-ui/REFRACTOR_GUIDE.md

# Refactor Guide – Deep Dive into the Khata‑UI Codebase

> This document walks through the entire repository, explains the current architecture, and provides a step‑by‑step refactor plan that will improve maintainability, type safety, and UI/UX while preserving the existing functional behavior.

---

## 1. Repository Layout (high‑level)
```
khata-ui/
├─ react-openapi/          # Core UI generated from OpenAPI configs
│   ├─ components/         # UI pieces: EnhancedTable, FilterBar, etc.
│   ├─ types/              # TypeScript interfaces (config, overrides)
│   └─ utils/              # Helper utilities (options, template resolution)
├─ src/                    # Application entry point and pages
│   ├─ auth/               # Authentication context, hooks, and protected routes
│   ├─ pages/              # Dynamic resources (list, form)
│   └─ main.tsx            # React root, providers, theming
├─ public/                 # Static assets (favicon, index.html)
├─ index.html
├─ package.json
└─ tsconfig.json
```

### Key Concepts
| Area | Responsibility |
|------|-----------------|
| **Auth** | Central JWT handling, `AuthProvider`, `useAuth`, route guarding. |
| **OpenAPI‑driven UI** | Describes each resource via `ResourceConfig`/`ResourceField`. Generates tables, filters, and forms automatically. |
| **Data Layer** | TanStack Query (`useQuery`) fetches data; Axios instance carries auth token via interceptor. |
| **Theming** | MUI theme with light/dark mode toggle (future). |
| **Extensibility** | `components` prop on `EnhancedTable` / `FilterBar` lets callers inject custom cell renderers, filter widgets, or action buttons. |

---

## 2. Detailed Module Walk‑through
### 2.1 `react-openapi/types/config.ts`
```ts
export interface ResourceField {
    displayFormat: string;          // <- single source of truth for rendering
    type: FieldType;
    label: string;
    required?: boolean;
    options?: string[];
    readOnly?: boolean;
    schema?: Record<string, ResourceField>;
    formatter?: (value: any) => string;
    relation?: string;
    filterType?: "autocomplete" | "multiselect" | "number-range" | "date-range";
    enumOption?: EnumOption;
    enumLabels?: Record<string, string>;
}
```
- `displayFormat` replaces the legacy `displayField`. It can be a **template string** (`"{{first}} {{last}}"`) or an **array of keys** for concatenation.
- All UI components now rely exclusively on this field.

### 2.2 `react-openapi/utils/options.ts`
- `resolveTemplate(format: string, item: any)` – interpolates `{{key}}` placeholders.
- `getFieldOptions`, `toGridValueOptions` convert enum definitions into MUI‑compatible arrays.
- **Refactor idea**: Move the `displayFormat` resolution logic from `EnhancedTable`/`FilterBar` into a dedicated helper (`formatDisplay(item, field)`), reducing duplication.

### 2.3 `react-openapi/components/EnhancedTable.tsx`
- **Core responsibilities**
  1. Build column definitions from `config.fields`.
  2. Render each cell via `FieldRenderer`.
  3. Provide server‑side or client‑side pagination.
  4. Add a static "Actions" column.
- **Key functions**
  - `getFormattedDisplayValue(item, displayFormat?, enumValue?)` – now uses `resolveTemplate` and falls back to generic fields.
  - `FieldRenderer` – decides how to render a cell based on `field.type`, `field.relation`, custom renderers, and `displayFormat`.
- **Duplication**: Both `EnhancedTable` and `FilterBar` perform very similar `displayFormat` extraction. Extracting this into a shared utility will shrink the component size and make testing easier.

### 2.4 `react-openapi/components/FilterBar.tsx`
- Generates filter controls for each **filterable** field.
- Uses `extractOptions` to populate autocomplete lists, falling back to `displayFormat` for label generation.
- **Opportunity**: Replace the inline `pull` helper with the shared formatter from `utils/options`.

### 2.5 Authentication (`src/auth`)
- `AuthContext.tsx` – provides `user`, `accessToken`, `isAuthenticated` plus actions.
- `useAuth.ts` – thin wrapper exposing the context values.
- `ProtectedRoute.tsx` – guards routes, redirects to `/login` when unauthenticated.
- `api.ts` – thin Axios wrapper (`login`, `logout`, `refresh`).
- **Refactor suggestions**
  - Consolidate token storage (localStorage ↔ sessionStorage) behind a small `tokenStore` service.
  - Add automatic token refresh using an interceptor that retries the original request.
  - Provide a hook (`useAuthorizedQuery`) that injects the auth token into TanStack Query automatically.

### 2.6 Application Core (`src/pages`, `src/main.tsx`)
- `ResourceList.tsx` – reads `resource` param, loads the related `ResourceConfig` from a central map, fetches data, and renders `EnhancedTable` + `FilterBar`.
- `ResourceForm.tsx` – builds a dynamic form based on `ResourceField` definitions; uses `displayFormat` for default values on relation fields.
- `main.tsx` – wraps the app with `AuthProvider`, `QueryClientProvider`, and MUI `ThemeProvider`.
- **Future work**: Extract the “resource loader” into a hook (`useResourceConfig(resourceName)`) that also validates the config at runtime.

---

## 3. Refactor Roadmap – Step‑by‑Step
### Phase 1 – Consolidate Formatting Logic
1. **Create utility** `src/react-openapi/utils/formatDisplay.ts`
   ```ts
   export const formatDisplay = (item: any, field: ResourceField, enumValue?: string) => {
       if (enumValue) return resolveTemplate(enumValue, item);
       const fmt = field.displayFormat;
       if (!fmt) return item.name ?? item.title ?? item.label ?? item.id ?? JSON.stringify(item);
       if (Array.isArray(fmt)) {
           return fmt.map(k => item[k]).filter(Boolean).join(' ');
       }
       return resolveTemplate(fmt, item) || item.id || JSON.stringify(item);
   };
   ```
2. Replace *all* inline calls to `getFormattedDisplayValue` in `EnhancedTable` and `FilterBar` with `formatDisplay`.
3. Remove `getFormattedDisplayValue` from `EnhancedTable.tsx` (or keep it as a thin wrapper for backward compatibility).
4. Update imports accordingly.
5. Run TypeScript check – no errors.

### Phase 2 – Decouple UI from Config Loading
- Introduce **`configLoader.ts`** under `src/react-openapi/utils` that reads a JSON file (or fetches a remote spec) and produces a `Record<string, ResourceConfig>`.
- Replace hard‑coded imports in `src/pages/ResourceList.tsx` with a call to `useResourceConfig(resourceName)`.
- Add runtime validation (e.g., using `zod`) to ensure required fields (`displayFormat`, `type`, `label`) are present; surface errors via a toast.

### Phase 3 – Centralize Error & Loading UI
- Create `src/components/LoadingSpinner.tsx` and `src/components/ErrorToast.tsx`.
- Wrap all data‑fetching hooks (`useResource`, `useAuth` actions) with a HOC that automatically displays these components.
- Migrate the scattered `if (loading) …` checks into the new components.

### Phase 4 – Theming & Dark Mode
1. Add a `ThemeContext` that stores `mode: 'light' | 'dark'` and persists the preference.
2. Expose a toggle button (e.g., in the top‑right corner of `App.tsx`).
3. Update component styles to use theme‑aware colors (via `theme.palette`), ensuring the `Chip` variants already respect the palette.

### Phase 5 – Testing & CI
- **Unit tests** using `vitest` for:
  - `formatDisplay` utility (various template & array cases).
  - `AuthProvider` behavior (login, logout, token refresh).
- **Component tests** (`@testing-library/react`) for `EnhancedTable` and `FilterBar` verifying that `displayFormat` rendering matches expectations.
- Add a GitHub Actions workflow that runs `npm run lint && npx tsc --noEmit && vitest run` on each PR.

### Phase 6 – Documentation (the files you will publish)
- **DESIGN.md** – high‑level architecture (already present).
- **IMPLEMENTATION.md** – detailed file‑by‑file breakdown (already present).
- **CONCEPT.md** – why the metadata‑driven approach works (already present).
- **REFRACTOR_GUIDE.md** – the detailed guide you are reading now (this file).
- Keep these files in the repo root; they can be exported to the **lovable** platform directly.

---

## 4. Migration Checklist (what to verify after refactor)
- [ ] All UI components compile with TypeScript (`npx tsc --noEmit`).
- [ ] No runtime references to `displayField` remain (search `\.displayField`).
- [ ] `formatDisplay` correctly resolves:
  - Template strings with multiple placeholders.
  - Array of keys.
  - Fallback to generic fields.
- [ ] Auth flow works (login ➜ token stored ➜ API requests succeed, protected routes guarded).
- [ ] Pagination works both client‑ and server‑side.
- [ ] Mobile layout (card view) still renders correctly.
- [ ] Dark‑mode toggle persists across reloads.
- [ ] Lint passes (`npm run lint` if configured) and tests pass.

---

## 5. Potential Future Enhancements
| Feature | Benefit | Rough Implementation |
|---------|---------|----------------------|
| **Bulk actions** (delete, export) | Improves admin productivity | Add a toolbar with selection model in `EnhancedTable`. |
| **Inline editing** | Faster data tweaks | Replace `onEdit` dialog with cell‑level edit mode using MUI `TextField`. |
| **GraphQL fallback** | Flexibility for back‑ends | Abstract data fetching behind an adapter interface (`useDataProvider`). |
| **Internationalisation** | Multi‑language UI | Wrap all static strings with `i18n.t()` and provide locale files. |
| **Performance profiling** | Identify render bottlenecks | Use React Profiler and memoize expensive formatters (`useMemo`). |

---

### Closing Note
The current codebase already demonstrates a powerful pattern: **declare once, render everywhere**. By consolidating the display logic, adding a small utility layer, and strengthening the authentication and theming foundations, the project will become easier to extend, test, and hand‑off to the **lovable** UI platform while retaining its low‑code advantage.