Admin Portal Full Stack Feature

Available request wrappers:

Authenticated (includes auth token from localStorage):

• authenticatedGet<T>(uri: string) - GET with auth token
• authenticatedPost<T>(uri: string, body: any) - POST with auth token
• authenticatedPatch<T>(uri: string, body: any) - PATCH with auth token
• authenticatedDelete<T>(uri: string, body: any) - DELETE with auth token
• fetchWithAuth<T>(path: string, options?: RequestInit) - Deprecated. Prefer using other wrappers. Custom fetch with auth token

Unauthenticated (for public endpoints):

• post<T>(uri: string, body: PostBody) - POST without auth token
• get<T>(uri: string) - GET without auth token (not exported, use authenticatedGet instead)

Call from React components

// For GET requests
const { data, isLoading } = useQuery({
  queryKey: ['invoices', clientId],
  queryFn: () => getInvoices(clientId),
});

// For mutations (POST/PATCH/DELETE)
const mutation = useMutation({
  mutationFn: createPayment,
  onSuccess: () => queryClient.invalidateQueries(['invoices']),
});

Frontend: Components

Refer to @../admin-portal-frontend-components/SKILL.md

Backend: Routes

Route Structure

Admin routes typically follow these patterns:

• Admin-specific routes: /backend/app.js under router.use('/admin', Auth.rejectNonSnoutUsers) (line 516+)
• General authenticated routes: /backend/app.js main router with Auth.hasVetId() or Auth.rejectNonSnoutUsers
• Controllers/handlers: /backend/ in semantically named files (e.g., clients.js, payment_request.js, vets.js)

Common auth middleware:

• Auth.rejectNonSnoutUsers - Only allow Snout internal users (admins)
• Auth.hasVetId() - Require vet_id in token (vets or admins viewing vet data)

1. Define the route in /backend/app.js (route definition only):

// Admin-only route example
router.get('/admin/payment_requests',
  Auth.rejectNonSnoutUsers,
  PaymentRequest.listPaymentRequests
);

// Vet or admin route example
router.get('/invoices',
  Auth.hasVetId(),
  Invoices.listInvoicesAdmin
);

2. Implement the handler in a semantically appropriate file under /backend/:

• Controllers: Existing files like backend/clients.js, backend/payment_request.js, backend/vets.js
• Services: /backend/services/ - business logic
• Middleware: /backend/middleware/ - auth, validation, etc.
• Workflows: /backend/workflows/ - complex multi-step operations
• DML: /backend/dml/ - data access layer

DO NOT

• Write handler implementation directly in route files
• Mix business logic into route definitions
• Skip auth middleware on protected routes
• Use raw SQL for simple CRUD operations (use DML layer instead)

Testing

E2E tests use Playwright and live in /admin-portal/e2e/.