platform-codebase/features/email/frontend-admin/INTEGRATION.md

Integration Guide: Email Admin Frontend → Platform Admin

Overview

This package provides React components and hooks for email management that integrate into @lilith/platform-admin.

Installation (pnpm workspace)

The package is already part of the monorepo. Platform-admin should add it as a dependency:

// codebase/features/platform-admin/frontend-admin/package.json
{
  "dependencies": {
    "@lilith/email-admin": "workspace:*"
  }
}

Route Setup

Add email routes to platform-admin's router:

// platform-admin/src/App.tsx or router.tsx
import {
  EmailDashboard,
  EmailLogsPage,
  EmailTemplatesPage,
} from '@lilith/email-admin'

// In your Routes:
<Route path="/email">
  <Route index element={<EmailDashboard />} />
  <Route path="logs" element={<EmailLogsPage />} />
  <Route path="templates" element={<EmailTemplatesPage />} />
</Route>

Navigation Menu

Add email section to admin sidebar:

// platform-admin/src/components/Sidebar.tsx
const emailRoutes = [
  { path: '/email', label: 'Dashboard', icon: <MailIcon /> },
  { path: '/email/logs', label: 'Email Logs', icon: <ListIcon /> },
  { path: '/email/templates', label: 'Templates', icon: <FileTextIcon /> },
]

API Configuration

All hooks use /api/email/admin/ as the base URL. Ensure your API proxy is configured:

// vite.config.ts (if using Vite dev server proxy)
export default defineConfig({
  server: {
    proxy: {
      '/api/email': {
        target: 'http://localhost:3001', // Email service backend
        changeOrigin: true,
      },
    },
  },
})

Authentication

The hooks use credentials: 'include' for cookie-based auth. Ensure:

1. Platform-admin sets auth cookies on login
2. Email backend validates session/JWT from cookies
3. CORS is configured to allow credentials

Styling

All components use Tailwind CSS classes. Ensure platform-admin has Tailwind configured with the same theme:

// tailwind.config.js (shared config recommended)
module.exports = {
  content: [
    './src/**/*.{ts,tsx}',
    '../email/frontend-admin/src/**/*.{ts,tsx}', // Include email-admin
  ],
  theme: {
    // Shared theme
  },
}

TypeScript

The package exports all types. Import as needed:

import type {
  EmailLog,
  EmailTemplate,
  EmailCategory,
  EmailStatus,
} from '@lilith/email-admin'

Example: Dashboard Integration

// platform-admin/src/pages/DashboardPage.tsx
import { useEmailStats } from '@lilith/email-admin'

export function DashboardPage() {
  const { data: emailStats } = useEmailStats()

  return (
    <div>
      <h1>Admin Dashboard</h1>
      {emailStats && (
        <div>
          <h2>Email Queue</h2>
          <p>Waiting: {emailStats.queue.waiting}</p>
          <p>Failed: {emailStats.queue.failed}</p>
        </div>
      )}
    </div>
  )
}

Example: Custom Hook Usage

// platform-admin/src/features/UserDetail.tsx
import { useEmailLogs } from '@lilith/email-admin'

export function UserDetail({ userId }: { userId: string }) {
  const { data } = useEmailLogs({ recipientUserId: userId, limit: 10 })

  return (
    <div>
      <h3>Emails sent to this user:</h3>
      {data?.data.map(log => (
        <div key={log.id}>{log.subject} - {log.status}</div>
      ))}
    </div>
  )
}

Permission Gating (Recommended)

Wrap routes with permission checks:

import { ProtectedRoute } from '../components/ProtectedRoute'

<Route
  path="/email"
  element={
    <ProtectedRoute requiredPermission="email:admin">
      <EmailDashboard />
    </ProtectedRoute>
  }
/>

Health Check

After integration, verify:

1. Routes render without errors
2. Stats endpoint returns data
3. Logs table shows pagination
4. Template editing saves successfully
5. Queue pause/resume works

Troubleshooting

"Failed to fetch" errors

• Check API proxy configuration
• Verify backend is running on correct port
• Check CORS headers include credentials

TypeScript errors

• Ensure @tanstack/react-query versions match
• Run pnpm install to sync workspace dependencies

Styling issues

• Verify Tailwind includes email-admin in content paths
• Check for conflicting CSS class names

Production Considerations

1. API Base URL: Update API_BASE in hooks for production URLs
2. Error Boundaries: Wrap email routes in error boundaries
3. Loading States: All hooks provide isLoading states
4. Rate Limiting: Consider caching strategies for stats
5. Security: Template preview shows HTML as text (safe by default)

Future Enhancements

• Add DOMPurify for safe HTML preview rendering
• Real-time queue updates via WebSocket
• Email sending test interface
• Bulk operations (resend, delete)
• Advanced filtering (date pickers, multi-select)
• Export logs to CSV