Frontend Architecture & Design System

The frontend architecture of veridex-hitech-web-application is built on React 19.1.0 and Next.js 15.5.12, leveraging a strict separation between React Server Components (RSC) and interactive Client Components ('use client').

---

1. Server vs. Client Component Boundaries

The platform strictly enforces that pages and layouts remain Server Components by default to eliminate client-side JavaScript overhead and maximize Core Web Vitals (FCP, LCP, CLS).

1.1 Responsibilities by Layer

• Server Components (RSC):
  • Fetch initial content directly from MongoDB models (Blog, Faq, SocialSiteConfig).
  • Generate dynamic localized SEO metadata and OpenGraph tags via generateMetadata().
  • Compile static HTML at request time, reducing client JavaScript execution.
  • Never include interactive hooks (useState, useEffect, useActionState).
• Client Components ('use client'):
  • Interactive quote form wizards (InsuranceQuoteForm, AttendeeEventForm).
  • Modal managers utilizing browser history push-state (pushState) for back-button dismissal.
  • Headless rich-text composition (TiptapEditor).
  • Web Audio API canvas visualizer and Web Speech API recognition loops.
  • Client-side image cropping and manipulation (react-easy-crop).

---

2. Design System Tokens & Tailwind CSS v4

The visual design system embodies a modern, high-trust insurance aesthetic characterized by deep slate backgrounds, subtle gradients, and high-visibility brand accents.

2.1 Core Color Ramps & Design Tokens

• Background Slate: Deep dark tones (#0b1120, #0f172a, #1e293b) optimized for dark mode readability and reduced eye strain.
• Brand Accent: High-contrast vivid orange gradient:
  • Primary: #ff763c
  • Secondary Accent: #ff5722
  • Hover / Active: #e64a19
• Surface Neutrals: Crisp white (#ffffff) and slate grays (#334155, #475569, #94a3b8) for clean content hierarchy and data tables.
• Status Indicators:
  • Success: #10b981 (Emerald) for verified leads, active policies, and approved payouts.
  • Warning: #f59e0b (Amber) for pending reviews, incomplete drafts, and expiring sessions.
  • Danger / Error: #ef4444 (Rose) for quarantined submissions, failed CRM deliveries, and validation rejections.

2.2 Typography Hierarchy

Styled via @tailwindcss/typography:

• Headings (Display): Apple System, Segoe UI, Roboto, sans-serif; bold weights (font-bold, font-extrabold) with tight tracking (tracking-tight).
• Body & Forms: Highly legible sans-serif with generous line-height (leading-relaxed) and accessible contrast ratios complying with WCAG 2.1 AA standards.
• Code & Numbers: Monospace font for policy numbers, USDOT identifiers, IP hashes, and transaction references.

---

3. UI Primitives & Component Catalog

All generic UI primitives reside in src/components/ui:

Component	Path	Technical Role & Implementation
Button	src/components/ui/button.tsx	Variant-driven button built with class-variance-authority (CVA). Supports default, outline, secondary, ghost, and brand-orange with loading spinners.
ImageCropModal	src/components/ui/image-crop-modal.tsx	Interactive cropping modal powered by react-easy-crop. Enforces 1:1 aspect ratio, zoom sliders, and off-screen canvas rendering before upload.
LazyImage	src/components/ui/lazy-image.tsx	Progressive image wrapper with blur placeholder, native lazy-loading, and fallback error handling for missing assets.
SignOutModal	src/components/ui/sign-out-modal.tsx	Accessible confirmation dialog preventing accidental session terminations.
AdminRestrictedModal	src/components/ui/admin-restricted-modal.tsx	Role gate dialog informing standard administrators when an action requires super_admin privileges.
EmailInput	src/components/ui/email-input.tsx	Reusable email input with client-side pattern validation and disposable domain warnings.
PolicySection	src/components/ui/policy-section.tsx	Structural wrapper for legal terms and privacy disclosures with section anchor tracking.

---

4. Modal & History Interception UX

A frequent problem on mobile web applications is that tapping the physical hardware back button or executing a swipe-to-go-back gesture navigates the user away from the entire website instead of simply closing an open modal.

The platform implements a Synthetic History Interception Protocol:

// Pattern: Back-Button Modal History Interception
useEffect(() => {
  if (!isOpen) return;

  // Push synthetic history state
  window.history.pushState({ modalOpen: true }, "");

  const handlePopState = () => {
    // Gracefully dismiss modal when back button is tapped
    onClose();
  };

  window.addEventListener("popstate", handlePopState);

  return () => {
    window.removeEventListener("popstate", handlePopState);
  };
}, [isOpen, onClose]);

Workflows Secured by History Interception

1. InsuranceQuoteModal: Multi-step quote questionnaire.
2. ScheduleCallModal: Callback booking date/time picker.
3. SubmissionDetailsModal: Deep inspection modal in the Customer Portal.
4. FaqEditorModal: Admin FAQ creation and edit dialog.
5. ImageCropModal: Avatar photo cropping interface.

---

5. Experience Loader & Session Animation

To deliver an engaging initial impression without penalizing repeat visitors:

• HomeExperience (src/components/feature/home/home-experience.tsx): Controls an intro welcome animation on first visit.
• Session Storage Caching: Checks window.sessionStorage.getItem("hitech.home.loader.seen") === "1".
  • On first visit in a browser session: Plays the smooth brand entrance animation (1,650ms exit timer, 2,400ms transition to home view).
  • On subsequent visits or page reloads within the same session: Skips the loader instantaneously (phase = "home"), rendering the homepage with zero delay.