FAQ System & Submissions
Relevant source files
The following files were used as context for generating this wiki page:
The FAQ System & Submissions module provides a full-stack solution for managing frequently asked questions, user-submitted inquiries, and administrative moderation. It enables public users to browse, search, and expand FAQ entries while providing a gated interface for administrators to triage submissions and publish content.
The system is integrated across multiple layers of the application, including the main landing page, a dedicated FAQ page, and an administrative dashboard backed by Cloudflare D1.
Sources: src/app/faq/page.tsx:1-12, src/app/admin/faq/page.tsx:1-35, tests/homepage-structure.test.tsx:90-100
Public Interface & Discovery
The public interface consists of a high-level summary on the homepage and a comprehensive dedicated FAQ page.
FAQ Section (Homepage)
The FAQSection component serves as a discovery point on the site's main page. It displays a limited subset of FAQ entries (top 5 by default, or 10 when searching) and includes call-to-action buttons for viewing all questions or submitting a new one.
Sources: src/components/FAQSection.tsx:75-155, tests/homepage-structure.test.tsx:85-110
Dedicated FAQ Page
The /faq page provides a full-featured browsing experience. It utilizes the apiGet utility to fetch items from /api/faq/list with a default limit of 50. Key features include:
- Search and Filtering: Client-side filtering allows users to search both questions and answers.
- Expansion Logic: Users can expand multiple items simultaneously to view full answers.
- Analytics Tracking: Expanding an item triggers an optimistic UI view count increment and a fire-and-forget
POSTrequest to/api/faq/view.
Sources: src/app/faq/page.tsx:43-125, tests/faq-page.test.tsx:95-115
The flow of user interaction on the public FAQ page, showing the relationship between UI updates and background API calls.
Sources: src/app/faq/page.tsx:77-101
FAQ Data Structures
The system relies on standardized TypeScript types to ensure consistency between the API, frontend, and administrative tools.
| Field | Type | Description |
|---|---|---|
id | number | Unique identifier for the FAQ or submission. |
question | string | The user's query or the established FAQ question. |
answer | string | The approved response displayed to users. |
status | string | Moderation state (e.g., pending, approved, rejected, archived). |
pinned | boolean / number | Priority flag; pinned items appear at the top of lists. |
view_count | number | Incremental counter for user engagement. |
updated_at | string | ISO8601 timestamp of the last modification. |
Sources: src/app/faq/page.tsx:10-17, src/app/admin/faq/page.tsx:10-34, tests/faq-moderation.test.ts:31-35
Administrative Moderation & Triage
The administrative interface located at /admin/faq provides two distinct workflows: the Ask Inbox and the FAQ CMS.
Ask Inbox Workflow
The Ask Inbox allows administrators to triage user-submitted questions. Submissions enter a "pending" queue where admins can:
- Approve: Optionally providing a public answer. If an answer is provided, a new FAQ entry is automatically created.
- Reject/Archive: Dismissing the submission with optional internal moderation notes.
Sources: src/app/admin/faq/page.tsx:180-250, tests/faq-moderation.test.ts:50-55
FAQ CMS Workflow
The CMS allows for the direct creation and editing of FAQ entries without an initial user submission. Admins can toggle "Published" status, "Pinned" status, and modify content.
Sources: src/app/admin/faq/page.tsx:255-320
The sequence of approving a user submission and converting it into a published FAQ entry.
Sources: src/app/admin/faq/page.tsx:120-135, src/app/admin/faq/page.tsx:215-230
Moderation Logic & Validation
The system employs specific helpers to ensure data integrity during moderation.
- Status Mapping: Ask inbox filters map to specific sets. "pending" includes both 'open' and 'pending' states. "rejected" includes both 'rejected' and 'hidden'.
- Validation: FAQ questions are required and must not be empty. Answers are required only if the item is being published.
- Authentication: Admin routes are protected by a fail-closed check requiring an
x-admin-tokenheader that matches the server'sADMIN_TOKEN.
Sources: tests/faq-moderation.test.ts:10-60
Sorting & Display Logic
Items are sorted using a multi-tier priority system:
- Pinned Items: Items with
pinned: 1are prioritized. - Recency: Within groups (pinned or unpinned), items are sorted by
updated_atin descending order.
Sources: src/app/faq/page.tsx:19-26, tests/faq-page.test.tsx:65-90
Conclusion
The FAQ System & Submissions module provides a robust framework for managing community knowledge and engagement. By combining an accessible public interface with structured administrative triage, it ensures that frequently asked questions are easily discoverable while allowing administrators to maintain high content standards through a governed publishing workflow.