mirror of
https://github.com/Sea-Haven-Industries/shoc-frontend-new.git
synced 2026-09-30 18:33:12 +00:00
042b9db2ac
* fix: correct Sea Haven branding in page title and wordmark * chore: use correct company name in docs and comments * docs: rewrite README * docs: add README badge block per github-standards * fix: update command syntax in deployment instructions * fix: replace template PWA icons and manifest branding * test: assert PWA manifest branding
544 lines
15 KiB
Markdown
544 lines
15 KiB
Markdown
# Sea Haven 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 │
|
|
│ (Sea Haven 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 Sea Haven UI! 🎊**
|
|
|
|
_Last updated: 2026_
|