whatshooked/web/FRONTEND_GUIDE.md

# WhatsHooked Frontend - Implementation Guide

## Current Status

Phase 2 Frontend is **IN PROGRESS** - Core structure created, needs completion.

### ✅ Completed
1. React + TypeScript + Vite project setup
2. Dependencies installed (react-router-dom, axios, zustand, @tanstack/react-query)
3. TypeScript types defined (`src/types/index.ts`)
4. API client with JWT handling (`src/lib/api.ts`)
5. Auth store with Zustand (`src/stores/authStore.ts`)
6. Login page component (`src/pages/LoginPage.tsx` + CSS)
7. Directory structure created

### 🚧 To Complete

#### 1. Main App Setup (`src/App.tsx`)
```typescript
import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useAuthStore } from './stores/authStore';
import LoginPage from './pages/LoginPage';
import DashboardLayout from './components/layout/DashboardLayout';
import DashboardPage from './pages/DashboardPage';
import HooksPage from './pages/HooksPage';
import AccountsPage from './pages/AccountsPage';
import EventLogsPage from './pages/EventLogsPage';
import UsersPage from './pages/UsersPage';

const queryClient = new QueryClient();

function PrivateRoute({ children }: { children: React.ReactNode }) {
  const { isAuthenticated } = useAuthStore();
  return isAuthenticated ? <>{children}</> : <Navigate to="/login" />;
}

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <BrowserRouter>
        <Routes>
          <Route path="/login" element={<LoginPage />} />
          <Route path="/" element={
            <PrivateRoute>
              <DashboardLayout />
            </PrivateRoute>
          }>
            <Route index element={<DashboardPage />} />
            <Route path="hooks" element={<HooksPage />} />
            <Route path="accounts" element={<AccountsPage />} />
            <Route path="logs" element={<EventLogsPage />} />
            <Route path="users" element={<UsersPage />} />
          </Route>
        </Routes>
      </BrowserRouter>
    </QueryClientProvider>
  );
}

export default App;
```

#### 2. Dashboard Layout (`src/components/layout/DashboardLayout.tsx`)
- Sidebar navigation
- Header with user info + logout
- Outlet for nested routes

#### 3. Pages to Create
- `DashboardPage.tsx` - Overview with stats
- `HooksPage.tsx` - CRUD for webhooks
- `AccountsPage.tsx` - Manage WhatsApp accounts
- `EventLogsPage.tsx` - View event logs
- `UsersPage.tsx` - User management (admin only)

#### 4. Reusable Components
- `components/layout/Sidebar.tsx`
- `components/layout/Header.tsx`
- `components/hooks/HookList.tsx`
- `components/hooks/HookForm.tsx`
- `components/accounts/AccountList.tsx`
- `components/accounts/AccountForm.tsx`

#### 5. Environment Configuration
Create `.env` file:
```
VITE_API_URL=http://localhost:8080
```

## API Endpoints Available

All endpoints auto-generated by ResolveSpec backend:

```
Auth:
  POST /api/v1/auth/login
  POST /api/v1/auth/logout

CRUD (GET, POST, PUT, DELETE):
  /api/v1/users
  /api/v1/hooks
  /api/v1/whatsapp_accounts
  /api/v1/api_keys
  /api/v1/event_logs
  /api/v1/sessions

Health:
  GET /health
```

## Running the Frontend

```bash
cd web
npm install
npm run dev  # Starts on http://localhost:5173
```

## Building for Production

```bash
cd web
npm run build  # Output to web/dist
```

## Integration with Backend

The Go API server can serve the frontend:

1. Build React app: `cd web && npm run build`
2. Update `pkg/api/server.go` to serve static files from `web/dist`
3. Add to router:
   ```go
   router.PathPrefix("/").Handler(http.FileServer(http.Dir("./web/dist")))
   ```

## Key Features to Implement

### Hooks Management
- List all webhooks with status (active/inactive)
- Create new webhook with:
  - Name, URL, HTTP method
  - Custom headers (JSON editor)
  - Event subscriptions (checkboxes)
  - Retry settings
- Edit/Delete webhooks
- Test webhook (send test event)

### WhatsApp Accounts
- List connected accounts with status
- Add new account:
  - Phone number
  - Account type (whatsmeow/business-api)
  - Show QR code for whatsmeow
  - API credentials for business-api
- Disconnect/reconnect accounts
- View account details

### Dashboard Stats
- Total hooks (active/inactive)
- Connected WhatsApp accounts
- Recent events (last 10)
- Success/failure rate chart

### Event Logs
- Paginated table view
- Filter by: event_type, success/failure, date range
- View full event data (JSON viewer)
- Export logs (CSV/JSON)

## Styling Approach

Using vanilla CSS with:
- CSS Grid/Flexbox for layouts
- CSS Variables for theming
- Gradient backgrounds (purple theme)
- Responsive design (mobile-friendly)

## State Management

- **Zustand**: Auth state (user, token)
- **React Query**: Server state (hooks, accounts, logs)
- Local state: Form inputs, UI toggles

## Next Steps

1. Complete App.tsx with routing
2. Build DashboardLayout component
3. Create all page components
4. Add form components for CRUD operations
5. Test with backend API
6. Add error handling and loading states
7. Responsive design testing
8. Build and deploy

## File Structure

```
web/
├── src/
│   ├── components/
│   │   ├── layout/
│   │   │   ├── DashboardLayout.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   └── Header.tsx
│   │   ├── hooks/
│   │   │   ├── HookList.tsx
│   │   │   └── HookForm.tsx
│   │   ├── accounts/
│   │   │   ├── AccountList.tsx
│   │   │   └── AccountForm.tsx
│   │   └── ...
│   ├── pages/
│   │   ├── LoginPage.tsx ✅
│   │   ├── DashboardPage.tsx
│   │   ├── HooksPage.tsx
│   │   ├── AccountsPage.tsx
│   │   ├── EventLogsPage.tsx
│   │   └── UsersPage.tsx
│   ├── lib/
│   │   └── api.ts ✅
│   ├── stores/
│   │   └── authStore.ts ✅
│   ├── types/
│   │   └── index.ts ✅
│   ├── App.tsx
│   └── main.tsx
├── package.json
└── vite.config.ts
```

## Notes

- Backend is 100% complete and ready
- Frontend structure is set up, needs page implementations
- All API calls are defined in `lib/api.ts`
- JWT auth is fully handled by axios interceptors
- Use React Query for data fetching/mutations