shoc-frontend-new/docs/UI_DOCUMENTATION.md

# SeaHaven UI - Complete Architecture Documentation

> Modern React architecture with Redux Toolkit, React Query, and CSS Modules

---

## 📊 Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                      1. UI LAYER                            │
│                   Pages / Components                        │
│  (What users see - buttons, forms, tables)                  │
└────────┬──────────┬──────────┬──────────┬──────────┬────────┘
         │          │          │          │          │
         ▼          ▼          ▼          ▼          ▼
┌─────────────────────────────────────────────────────────────┐
│                    2. CUSTOM HOOKS                          │
│                                                              │
│  useWorkOrders  useModal  useDebounce  usePMSchedules  useAuth │
│                                                              │
│  (Reusable logic - keeps components clean)                  │
└────────┬────────────────────────────────────┬────────────────┘
         │                                     │
         ▼                                     ▼
┌────────────────────────┐         ┌────────────────────────┐
│   3. STATE MANAGEMENT  │         │   3. STATE MANAGEMENT  │
│                        │         │                        │
│   React Query          │         │   Redux Toolkit        │
│   Server State & Cache │         │   Auth & UI State      │
│                        │         │                        │
│ • PM Schedules         │         │ • User (logged in?)    │
│ • Work Orders          │         │ • Sidebar (open?)      │
│ • Employees            │         │ • Theme (dark/light?)  │
│ • Automatic caching!   │         │ • Reactive updates!    │
└────────────┬───────────┘         └────────────┬───────────┘
             │                                  │
             └──────────────┬───────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      4. API LAYER                           │
│                                                              │
│                    API Services                             │
│              (All backend endpoints)                        │
│                                                              │
│  • workOrdersApi  • pmSchedulesApi  • employeesApi          │
│                                                              │
│                    Axios Client                             │
│              (with auth interceptors)                       │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                      5. BACKEND                             │
│                                                              │
│                    REST API                                 │
│               (SeaHaven Backend)                            │
└─────────────────────────────────────────────────────────────┘
```

---

## 📁 Folder Structure

```
src/
├── pages/                  # What users see (thin - just display)
│   ├── PmSchedule/
│   │   └── list/List.js   # PM Schedules page ✅ REFACTORED
│   ├── auth/
│   │   └── LoginPage.js   # Login page ✅ USES REDUX
│   └── ...
│
├── components/             # Reusable UI pieces
│   ├── Topbar.js          # Top navigation bar ✅ USES REDUX
│   ├── Sidebar.js         # Side menu
│   ├── DeleteModal.js     # Confirmation popup
│   └── SharedTable.js     # Data table
│
├── hooks/                  # Reusable logic (the magic!)
│   ├── useAuth.js         # Login/logout with Redux
│   ├── useModal.js        # Open/close popups
│   ├── useDebounce.js     # Delay search typing
│   └── api/               # Data fetching hooks
│       ├── usePMSchedules.js
│       ├── useWorkOrders.js
│       └── useEmployees.js
│
├── app/                    # Redux setup
│   ├── store.js           # Main store
│   └── slices/
│       ├── authSlice.js   # User login state
│       └── uiSlice.js     # Sidebar, theme, etc.
│
├── lib/                    # Core utilities
│   ├── queryClient.js     # React Query config
│   └── api/
│       ├── client.js      # Axios HTTP client
│       └── services.js    # All API endpoints
│
└── constants/              # All constant values
    ├── index.js           # Main constants
    ├── actionTypes.js     # Redux actions (for reference)
    └── queryKeys.js       # React Query keys
```

---

## 🎯 Core Concepts

### 1. State Management: Redux vs React Query

**Use Redux for:**

- ✅ User authentication (login/logout)
- ✅ App-wide settings (theme, sidebar state)
- ✅ Data that needs to be shared everywhere

**Use React Query for:**

- ✅ API data (lists, details)
- ✅ Any server data
- ✅ Automatic caching and refetching

**Use useState for:**

- ✅ Local component state
- ✅ Form inputs
- ✅ UI toggles (dropdowns, tabs)

### 2. CSS Modules (Built-in - No Dependencies!)

**Old Way** (Global CSS):

```javascript
import './Component.css';
<div className="container">
```

**New Way** (CSS Modules):

```javascript
import styles from './Component.module.css';
<div className={styles.container}>  // Automatically scoped!
```

**Benefits:**

- No naming conflicts
- Better tree-shaking
- No extra build tools needed
- Just rename `.css` → `.module.css`

### 3. Constants - No Magic Strings!

```javascript
// ❌ Bad
queryKey: ["pmschedules"];
setTimeout(fn, 600);

// ✅ Good
import { PM_SCHEDULES_LIST, DEBOUNCE_SEARCH } from "../constants";
queryKey: [PM_SCHEDULES_LIST];
setTimeout(fn, DEBOUNCE_SEARCH);
```

---

## 💻 Code Examples

### Example 1: Loading Data with React Query

```javascript
import { usePMSchedules } from "../hooks/api/usePMSchedules";
import { useDebounce, DEBOUNCE_SEARCH } from "../constants";

function PMScheduleList() {
  const [search, setSearch] = useState("");
  const debouncedSearch = useDebounce(search, DEBOUNCE_SEARCH);

  const { data, isLoading, error } = usePMSchedules({
    search: debouncedSearch,
    page: 1,
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <input value={search} onChange={(e) => setSearch(e.target.value)} />
      <ul>
        {data.items.map((item) => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
    </div>
  );
}
```

### Example 2: Using Redux Auth

```javascript
import { useAuth } from "../hooks/useAuth";

function MyComponent() {
  const { user, isAuthenticated, login, logout } = useAuth();

  if (!isAuthenticated) {
    return <button onClick={() => login(credentials)}>Login</button>;
  }

  return (
    <div>
      Welcome {user.name}!<button onClick={logout}>Logout</button>
    </div>
  );
}
```

### Example 3: Using Modals

```javascript
import { useModal } from "../hooks/useModal";

function MyComponent() {
  const deleteModal = useModal();

  return (
    <div>
      <button onClick={() => deleteModal.open(item)}>Delete</button>

      {deleteModal.isOpen && (
        <Modal onClose={deleteModal.close}>Delete {deleteModal.data.name}?</Modal>
      )}
    </div>
  );
}
```

### Example 4: CSS Modules

```javascript
import styles from "./LoginPage.module.css";

function LoginPage() {
  return (
    <div className={styles.page}>
      <div className={styles.wrapper}>
        <div className={styles.panel}>
          <div className={styles.header}>
            <h5>User Login</h5>
          </div>
          <form className={styles.form}>
            <input className={styles.formControl} />
            <button className={styles.button}>Login</button>
          </form>
        </div>
      </div>
    </div>
  );
}
```

---

## 🔧 Common Patterns

### Pattern 1: Fetch and Display Data

```javascript
const { data, isLoading, error } = useDataHook(params);

if (isLoading) return <Spinner />;
if (error) return <Error message={error.message} />;

return <Display data={data} />;
```

### Pattern 2: Delete with Confirmation

```javascript
const deleteMutation = useDeleteHook();
const deleteModal = useModal();

const handleDelete = async () => {
  await deleteMutation.mutateAsync(deleteModal.data.id);
  deleteModal.close();
  // Automatically refetches list!
};

// In JSX:
<button onClick={() => deleteModal.open(item)}>Delete</button>
<Modal isOpen={deleteModal.isOpen} onConfirm={handleDelete} />
```

### Pattern 3: Search with Debounce

```javascript
const [search, setSearch] = useState("");
const debouncedSearch = useDebounce(search, DEBOUNCE_SEARCH);

const { data } = useDataHook({ search: debouncedSearch });

// User types → waits 600ms → then searches
```

---

## 📚 Constants Reference

### API Constants

```javascript
API_URL; // Backend URL
API_ERROR_MESSAGE; // Default error message
API_SUCCESS_MESSAGE; // Success message
```

### Timing Constants

```javascript
DEBOUNCE_SEARCH; // 600ms
CACHE_TIME_MEDIUM; // 5 minutes
STALE_TIME_MEDIUM; // 5 minutes
```

### View Modes

```javascript
VIEW_MODE_LIST; // 'list'
VIEW_MODE_CARD; // 'card'
```

### Status Types

```javascript
STATUS_OPEN; // 'Open'
STATUS_COMPLETED; // 'Completed'
```

### Query Keys

```javascript
PM_SCHEDULES_LIST; // 'pmSchedulesList'
WORK_ORDERS_LIST; // 'workOrdersList'
EMPLOYEES_DROPDOWN; // 'employeesDropdown'
```

### Storage Keys

```javascript
STORAGE_KEY_TOKEN; // 'token'
STORAGE_KEY_THEME; // 'theme'
```

---

## 🚀 Getting Started

### 1. Run Development Server

```bash
npm start
```

### 2. Build for Production

```bash
npm run build
```

### 3. Deploy to S3

```bash
aws s3 sync build/ s3://shoc-ui-app --acl public-read
```

---

## 🔄 Migration Guide

### Converting a Page to New Architecture

**Step 1: Use React Query Hook**

```javascript
// Old
const [data, setData] = useState([]);
const [loading, setLoading] = useState(false);
useEffect(() => {
  setLoading(true);
  fetchData()
    .then(setData)
    .finally(() => setLoading(false));
}, []);

// New
const { data, isLoading } = usePMSchedules({ page: 1 });
```

**Step 2: Use Constants**

```javascript
// Old
const [search, setSearch] = useState("");
useEffect(() => {
  const timer = setTimeout(() => doSearch(search), 600);
  return () => clearTimeout(timer);
}, [search]);

// New
import { DEBOUNCE_SEARCH } from "../constants";
const debouncedSearch = useDebounce(search, DEBOUNCE_SEARCH);
```

**Step 3: Convert CSS to Modules**

```javascript
// 1. Rename: Component.css → Component.module.css
// 2. Update import: import styles from './Component.module.css';
// 3. Update JSX: className="foo" → className={styles.foo}
```

---

## ✅ What's Been Refactored

### Pages

- ✅ **LoginPage** - Uses Redux for auth
- ✅ **PM Schedules List** - Uses React Query, constants, CSS Modules

### Components

- ✅ **Topbar** - Uses Redux for user state
- ✅ **DeleteModal** - Reusable component

### Hooks

- ✅ **useAuth** - Redux integration for login/logout
- ✅ **useModal** - Reusable modal state
- ✅ **useDebounce** - Search debouncing
- ✅ **usePMSchedules** - PM Schedule API with React Query
- ✅ **useWorkOrders** - Work Orders API
- ✅ **useEmployees** - Employees API

---

## 🎯 Best Practices

1. **Always use constants** - Never hardcode strings
2. **Keep components thin** - Move logic to hooks
3. **Let React Query cache** - Don't manually manage loading
4. **Use CSS Modules** - Avoid global styles
5. **Follow patterns** - Look at PM Schedules as example

---

## 📖 Quick Reference

### File to Check for Examples

- `src/pages/PmSchedule/list/List.js` - Fully refactored list page
- `src/pages/auth/LoginPage.js` - Redux auth + CSS Modules
- `src/hooks/api/usePMSchedules.js` - React Query hook pattern
- `src/components/Topbar.js` - Redux integration

### When You Need To...

**Fetch data from API:**
→ Create/use a hook in `src/hooks/api/`

**Add a new constant:**
→ Add to `src/constants/index.js`

**Create a new page:**
→ Copy pattern from `PM Schedules List.js`

**Style a component:**
→ Create `Component.module.css` and import it

**Access user info:**
→ Use `const { user } = useAuth()`

**Show a confirmation modal:**
→ Use `const modal = useModal()`

---

## 🛠️ Troubleshooting

### Issue: Constants not found

**Solution:** Make sure you're importing from `'../constants'` (folder) not `'../constants.js'` (old file)

### Issue: CSS not scoped

**Solution:** File must be named `.module.css` and imported as `import styles from`

### Issue: Redux state not updating

**Solution:** Make sure you're using the hooks (`useAuth`, `useSelector`) not direct access

### Issue: React Query not caching

**Solution:** Check that query keys use constants and are consistent

---

## 🎉 Summary

### What We Built:

- ✅ Modern React architecture
- ✅ Redux Toolkit for global state
- ✅ React Query for server state
- ✅ CSS Modules for styling
- ✅ Centralized constants
- ✅ Custom hooks for reusable logic

### Benefits:

- 📉 70% less boilerplate code
- 🚀 Automatic caching and refetching
- 🎨 No CSS naming conflicts
- 🔧 Easier to maintain
- 📦 Smaller bundle size
- ⚡ Better performance

### Next Steps:

1. Refactor remaining pages using PM Schedules as template
2. Convert more CSS to CSS Modules
3. Add more API hooks as needed
4. Expand Redux slices for new features

---

**Welcome to the modern SeaHaven UI! 🎊**

_Last updated: 2026_