Howden Client - High-Level Architecture

Version: 0.8.3

Overview

Howden Client is an insurance management web application built with Next.js 15 (Pages Router). It serves multiple user types across various insurance providers, providing features for member management, enrollment, and administrative operations.

Tech Stack

Category	Technology
Framework	Next.js 15 (Pages Router)
Language	TypeScript
Styling	TailwindCSS, shadcn/ui components
State Management	Zustand, React Query (TanStack Query)
Forms	React Hook Form + Zod validation
Authentication	NextAuth.js (Credentials Provider)
HTTP Client	Axios
Analytics	Vercel Analytics, Google Analytics
Testing	Vitest, Testing Library, Storybook
Rich Text Editor	BlockNote
Environment Validation	T3 Env
Security	reCAPTCHA
Package Manager	pnpm

Directory Structure


src/
├── assets/           # Static assets (images, fonts)
├── components/
│   ├── feature/      # Feature-specific components
│   │   ├── AuditLogs/
│   │   ├── BeneficiaryEnrollment/
│   │   ├── BeneficiaryInformation/
│   │   ├── BeneficiaryPortal/
│   │   ├── ClientCompanyList/
│   │   ├── CompanyInformation/
│   │   ├── Dialog/
│   │   ├── Editor/         # Rich text editor (BlockNote)
│   │   ├── Enrollment/
│   │   ├── Forms/
│   │   ├── InsuranceCompanies/
│   │   ├── IntellicareEnrollment/
│   │   ├── ManageInsurance/
│   │   ├── NotFound/
│   │   ├── PrincipalPortal/
│   │   ├── Tables/
│   │   ├── Tabs/
│   │   ├── Tooltip/
│   │   └── RootInjector.tsx
│   ├── icons/        # Custom icon components
│   ├── layouts/      # Page layout components
│   ├── providers/    # React context providers
│   └── ui/           # Reusable UI components (shadcn/ui)
├── constants/        # Application constants & enums
├── lib/
│   ├── analytics/    # Analytics utilities (Vercel, GA)
│   ├── hooks/        # Custom React hooks
│   ├── auth-options.ts   # NextAuth configuration
│   ├── excel-js.ts       # Excel export with exceljs
│   ├── excel.ts          # Excel utilities
│   ├── sentry.ts         # Error tracking config
│   └── toast.ts          # Toast notification utilities
├── pages/            # Next.js pages (routes)
│   ├── api/          # API routes (NextAuth)
│   ├── dashboard/
│   └── reset/
├── services/
│   └── api/          # API service layer
│       ├── HR/                    # HR-related endpoints
│       ├── audit-trail/           # Audit logging
│       ├── auth.ts                # Authentication
│       ├── beneficiary-enrollment/
│       ├── beneficiary-portal/
│       ├── beneficiary-provider/
│       ├── client-company/
│       ├── cocolife/
│       ├── etiqa/
│       ├── forgot-password/
│       ├── generali/
│       ├── icare/
│       ├── insurance-company-values/
│       ├── insurance-plan-schema.ts
│       ├── insurance-provider/
│       ├── intellicare/
│       ├── logged-in-users/
│       ├── maxicare/
│       ├── principal/
│       ├── reset-password/
│       ├── user/
│       ├── instance.ts            # Axios instances
│       ├── interface.ts           # API interfaces
│       └── response.ts            # Response types
├── styles/           # Global CSS
└── utils/            # Utility functions

Authentication Flow


┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Login     │────▶│  OTP Auth   │────▶│   Session   │
│   Page      │     │  (NextAuth) │     │   Created   │
└─────────────┘     └─────────────┘     └─────────────┘

User Types

User Type	Description	Access Level
Broker	Full administrative access	Complete system access
Principal	Company/HR representative access	PrincipalPortal, OpenEnrollment
Beneficiary	Individual member access	BeneficiaryPortal, enrollment workflows

Authentication Features

OTP-based login via next-auth/credentials
reCAPTCHA integration for security
JWT tokens with automatic refresh
Password reset flow with email verification
Session management with secure cookie handling

Insurance Providers

The application supports multiple insurance providers:

Cocolife
Etiqa
Generali
Icare
Intellicare
Maxicare

Each provider has dedicated:

API service modules (/services/api/{provider}/)
UI tabs and components
Data schemas and validation

API Architecture

Instance Configuration


// Public API - No authentication required
publicApi = axios.create({ baseURL: '/api/v1/public' })
 
// Private API - Requires access token
privateApi = (accessToken, { user, action }) => axios.create({
  baseURL: '/api/v1/private',
  headers: { Authorization: `Bearer ${accessToken}` }
})

API Service Pattern

Each API module follows a consistent pattern:


// 1. Raw API function
async function getAllMembers(credentials, params) {
  const response = await privateApi(credentials).get('/endpoint');
  return schema.parse(response.data);
}
 
// 2. React Query hook
function useMembers(params) {
  return useQuery({
    queryKey: ['members', ...params],
    queryFn: () => getAllMembers(credentials, params),
    enabled: isAuthenticated && hasRequiredParams,
  });
}

Data Validation

All API responses are validated using Zod schemas before being consumed by the application.

State Management

Server State (React Query)

API data fetching and caching
Automatic background refetching
Optimistic updates for mutations

Client State (Zustand)

UI state (filters, selections)
Form state persistence
Local preferences

Error Boundaries

React error boundaries catch rendering errors and display fallback UIs.

Middleware

The Next.js middleware (src/middleware.ts) handles:

Workspace Validation - Validates ?workspace= parameter
Sensitive Param Stripping - Removes passwords/credentials from URLs
Auth Protection - Redirects unauthenticated users via withAuth

Key Features

Member Information Management

Paginated data tables per insurance provider with @tanstack/react-table
Advanced filtering and search with debounced inputs
Excel export with formatting (exceljs, xlsx-js-style)
Column visibility controls

Enrollment Workflows

Beneficiary enrollment with multi-step forms
Open enrollment periods per provider
Intellicare enrollment specific workflow
Principal portal for company/HR management
Beneficiary portal for individual member access

Content Management

Rich text editor (BlockNote) for content creation
Company information management
Insurance plan schema configuration

Audit & Security

Audit trail tracking for all private API actions
Audit logs viewer with filtering
Sentry integration for error tracking
Vercel Analytics & Speed Insights
Google Analytics integration

Data Export

Excel generation with styling
File download utilities (file-saver)
Bulk data export capabilities

Performance Optimizations

Query Debouncing - Search/filter inputs debounced (1000ms)
Pagination - Data fetched in pages (default: 25 items)
Lazy Loading - Download data fetched only when needed
Session Replay Sampling - 10% session recording in production

Environment Configuration

Key environment variables (validated via T3 Env):

Variable	Purpose	Type
`NEXT_PUBLIC_API_ENDPOINT`	Backend API base URL	Public
`NEXT_PUBLIC_RECAPTCHA_SITE_KEY`	Google reCAPTCHA site key	Public
`NEXT_PUBLIC_SENTRY_DSN`	Sentry error tracking DSN	Public
`NEXT_PUBLIC_GA_ID`	Google Analytics ID	Public
`NEXTAUTH_SECRET`	NextAuth encryption key	Server
`NEXTAUTH_URL`	Application URL	Server
`SENTRY_AUTH_TOKEN`	Sentry build auth token	Server

Build & Deployment


pnpm install       # Install dependencies
pnpm dev           # Development server
pnpm build         # Production build
pnpm start         # Start production server
pnpm lint          # Run ESLint
pnpm test          # Run Vitest tests
pnpm type-check    # TypeScript type checking
pnpm storybook     # Start Storybook dev server
pnpm build-storybook # Build static Storybook

Development Tools

Storybook

Component documentation and testing with Storybook:


pnpm storybook       # Start Storybook dev server
pnpm build-storybook # Build static Storybook

T3 Environment Validation

Type-safe environment variables using @t3-oss/env-nextjs:

Runtime validation of env vars
TypeScript IntelliSense support
Separation of client/server variables