Skip to main content

Dynamic Bilingual FAQ Management

The HiTech FAQ System is a real-time, database-backed knowledge management engine that delivers localized, schema-validated questions and answers to prospective insurance buyers. Operating across English and Spanish locales, the system eliminates hardcoded FAQs and empowers agency operations to rapidly update policy explanations, claims instructions, and coverage limitations without code deployments.

1. Data Schema & Automatic Seeding Engine​

All FAQs are modeled in src/lib/db/models/Faq.ts and managed via Mongoose:

export interface IFaq {
  _id: string;
  question: string;
  answer: string;
  language: "en" | "es";
  order: number;              // Explicit integer sort sequence (1, 2, 3...)
  createdAt: Date;
  updatedAt: Date;
}

Zero-Configuration Automatic Database Seeding​

To prevent empty UI accordions or crashes in newly deployed environments, src/server/actions/faq.actions.ts provides a self-healing seed mechanism: ensureFaqSeed().

When the database collection contains 0 documents, ensureFaqSeed() automatically populates the collection with 8 verified foundational entries:

  • English:
    1. What types of businesses do you cover? (Transportation, technology, construction, retail, healthcare)
    2. How do I get a quote? (Online instant form or specialist phone line)
    3. Can I customize my insurance coverage? (Policy tailoring without paying for excess coverage)
    4. Do you work with multiple insurance carriers? (Broker network comparison)
  • Spanish:
    1. ¿Qué tipos de negocios aseguran?
    2. ¿Cómo puedo obtener una cotización?
    3. ¿Puedo personalizar mi cobertura de seguro?
    4. ¿Trabajan con varias compañías de seguros?

2. Server Action Suite (faq.actions.ts)​

The FAQ lifecycle is managed by strongly typed Next.js Server Actions:

Function SignatureAccess ControlPurpose
getFaqs(language?: "en" | "es")PublicRetrieves all active FAQs sorted by order: 1, createdAt: 1. Used by public pages and components.
getPaginatedFaqs(page, limit, search, language)AdminPaginated tabular view for the admin dashboard with full-text regex search across question and answer.
getFaqCounts()AdminReturns aggregate record counts { en: number, es: number, total: number } for tab badge counters.
createFaq(data: Partial<IFaq>)requireAdmin()Inserts a new question/answer pair, assigns the next order index, and triggers path revalidation.
updateFaq(id: string, data: Partial<IFaq>)requireAdmin()Updates question, answer, or language attributes, invalidating relevant client caches.
deleteFaq(id: string)requireAdmin()Deletes the document from MongoDB and revalidates public routes.
reorderFaqs(items: Array<{ id: string; order: number }>)requireAdmin()Executes a bulk MongoDB write (bulkWrite) updating the sort index of multiple items after drag-and-drop reordering.

Cache Invalidation Strategy​

Whenever mutations occur (createFaq, updateFaq, deleteFaq, reorderFaqs), the server actions automatically trigger Next.js On-Demand Revalidation:

revalidatePath("/faq");
revalidatePath("/admin");
revalidatePath("/insurance/[slug]", "page");

3. Search Engine Optimization & Google FAQPage Schema​

The platform automatically structures active FAQs into Google-compliant JSON-LD structured schemas using buildFaqSchema():

import { buildFaqSchema } from "@/lib/seo/schema-generators";
import { JsonLd } from "@/components/seo/json-ld";

export async function InsuranceDetailFaq({ faqs }: { faqs: IFaq[] }) {
  const schemaItems = faqs.map((f) => ({
    question: f.question,
    answer: f.answer,
  }));

  const faqJsonLd = buildFaqSchema(schemaItems);

  return (
    <>
      <JsonLd data={faqJsonLd} />
      <div className="faq-accordion-container">
        {/* Render Accordion */}
      </div>
    </>
  );
}

This structured markup allows Google search results to render rich expandable FAQ accordions directly within Search Engine Result Pages (SERPs), increasing organic click-through rates.

4. Admin Management Interface​

The FAQ administration center is located in Tab 12 of the Admin Control Center:

  • Language Switcher: Toggle between English and Spanish repositories with independent record counts.
  • Search & Filter: Real-time debounce query filtering across questions and answers.
  • Drag-and-Drop Reordering: Interactive reordering handles allowing administrators to visually re-sequence display order without manual numbering.
  • Modal Editor: Rich textarea inputs with real-time character count validation and preview.