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)

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

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

Building for Production

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:

   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