From 4b520d5983a60e8d2963f92fcdab943392981e26 Mon Sep 17 00:00:00 2001
From: Rootul Patel <rootulp@gmail.com>
Date: Wed, 15 Jul 2026 21:25:21 -0700
Subject: [PATCH] feat: add FAQ page explaining data source

Add a static /faq route answering where TriTimes gets its data (the
Competitor.com results API that powers IRONMAN's official results pages),
whether it's affiliated with IRONMAN, and how to report issues.

Q&A content and schema.org FAQPage JSON-LD live in a tested lib module;
the page renders them and a footer link makes it discoverable site-wide.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ErTFrsFRR8HEUpgL3YphHs
---
 app/src/app/faq/page.tsx          | 41 ++++++++++++++++++++++
 app/src/components/Footer.tsx     |  6 ++++
 app/src/lib/__tests__/faq.test.ts | 40 ++++++++++++++++++++++
 app/src/lib/faq.ts                | 56 +++++++++++++++++++++++++++++++
 4 files changed, 143 insertions(+)
 create mode 100644 app/src/app/faq/page.tsx
 create mode 100644 app/src/lib/__tests__/faq.test.ts
 create mode 100644 app/src/lib/faq.ts

diff --git a/app/src/app/faq/page.tsx b/app/src/app/faq/page.tsx
new file mode 100644
index 0000000..789e27f
--- /dev/null
+++ b/app/src/app/faq/page.tsx
@@ -0,0 +1,41 @@
+import type { Metadata } from "next";
+import { FAQ_ITEMS, buildFaqJsonLd } from "@/lib/faq";
+
+export const revalidate = false;
+
+export const metadata: Metadata = {
+  title: "FAQ",
+  description:
+    "Frequently asked questions about TriTimes — where the race data comes from, whether it's affiliated with IRONMAN, and how to report issues.",
+  alternates: { canonical: "/faq" },
+  openGraph: {
+    title: "FAQ",
+    description:
+      "Frequently asked questions about TriTimes — where the race data comes from and how it works.",
+    url: "/faq",
+  },
+};
+
+export default function FaqPage() {
+  return (
+    <main className="max-w-3xl w-full mx-auto px-4 py-8">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(buildFaqJsonLd()) }}
+      />
+      <h1 className="text-3xl font-bold text-white mb-8">
+        Frequently Asked Questions
+      </h1>
+      <dl className="space-y-8">
+        {FAQ_ITEMS.map((item) => (
+          <div key={item.question}>
+            <dt className="text-lg font-semibold text-white mb-2">
+              {item.question}
+            </dt>
+            <dd className="text-gray-400 leading-relaxed">{item.answer}</dd>
+          </div>
+        ))}
+      </dl>
+    </main>
+  );
+}
diff --git a/app/src/components/Footer.tsx b/app/src/components/Footer.tsx
index a7cf307..6fcfe26 100644
--- a/app/src/components/Footer.tsx
+++ b/app/src/components/Footer.tsx
@@ -10,6 +10,12 @@ export default function Footer() {
         >
           Stats
         </Link>
+        <Link
+          href="/faq"
+          className="text-sm text-gray-400 hover:text-white transition-colors"
+        >
+          FAQ
+        </Link>
         <a
           href="https://docs.google.com/forms/d/e/1FAIpQLScavYEE5U8S1Cx2OyLxFpDMPgNh5gcZh_VsbLawOBNkdYtNOQ/viewform"
           target="_blank"
diff --git a/app/src/lib/__tests__/faq.test.ts b/app/src/lib/__tests__/faq.test.ts
new file mode 100644
index 0000000..f559302
--- /dev/null
+++ b/app/src/lib/__tests__/faq.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { FAQ_ITEMS, buildFaqJsonLd } from "../faq";
+
+describe("FAQ_ITEMS", () => {
+  it("includes a question about where the data comes from", () => {
+    const item = FAQ_ITEMS.find(
+      (i) => /data/i.test(i.question) && /(come|source|get|scrap)/i.test(i.question),
+    );
+    expect(item).toBeDefined();
+    // The honest answer names the Competitor.com results API as the source.
+    expect(item!.answer.toLowerCase()).toContain("competitor.com");
+  });
+
+  it("has a non-empty question and answer for every item", () => {
+    expect(FAQ_ITEMS.length).toBeGreaterThan(0);
+    for (const item of FAQ_ITEMS) {
+      expect(item.question.trim().length).toBeGreaterThan(0);
+      expect(item.answer.trim().length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("buildFaqJsonLd", () => {
+  it("emits schema.org FAQPage structured data", () => {
+    const jsonLd = buildFaqJsonLd();
+    expect(jsonLd["@context"]).toBe("https://schema.org");
+    expect(jsonLd["@type"]).toBe("FAQPage");
+  });
+
+  it("emits one Question entity per FAQ item with a text Answer", () => {
+    const jsonLd = buildFaqJsonLd();
+    expect(jsonLd.mainEntity).toHaveLength(FAQ_ITEMS.length);
+    jsonLd.mainEntity.forEach((entity, i) => {
+      expect(entity["@type"]).toBe("Question");
+      expect(entity.name).toBe(FAQ_ITEMS[i].question);
+      expect(entity.acceptedAnswer["@type"]).toBe("Answer");
+      expect(entity.acceptedAnswer.text).toBe(FAQ_ITEMS[i].answer);
+    });
+  });
+});
diff --git a/app/src/lib/faq.ts b/app/src/lib/faq.ts
new file mode 100644
index 0000000..501ec63
--- /dev/null
+++ b/app/src/lib/faq.ts
@@ -0,0 +1,56 @@
+// Frequently-asked-questions content for the /faq page.
+//
+// Q&A data and the schema.org FAQPage builder live here (not in the page
+// component) so they can be unit-tested and so the page stays a thin renderer.
+// This module intentionally has no dependency on the heavy corpus in data.ts.
+
+export interface FaqItem {
+  question: string;
+  answer: string;
+}
+
+export const FAQ_ITEMS: FaqItem[] = [
+  {
+    question: "Where does TriTimes get its data?",
+    answer:
+      "TriTimes reads results from the same Competitor.com results API (labs-v2.competitor.com) that powers IRONMAN's own official results pages. It is not HTML-scraping the results table, and it is not a public or documented third-party API — it's the same undocumented endpoint the official site itself uses to load results. For each event we read the ironman.com results page once to find that event's ID, then fetch its results as JSON.",
+  },
+  {
+    question: "Is TriTimes affiliated with IRONMAN?",
+    answer:
+      "No. TriTimes is an independent, unofficial project and is not affiliated with, endorsed by, or sponsored by The IRONMAN Group or Competitor.com. All race data belongs to its respective owners.",
+  },
+  {
+    question: "Why is a result missing or incorrect?",
+    answer:
+      "TriTimes mirrors what the official results publish, so missing splits, misspelled names, or wrong age groups usually originate in the source data. If a result looks wrong or a race is missing, let us know through the Feedback link in the footer and we'll take a look.",
+  },
+];
+
+export interface FaqJsonLd {
+  "@context": "https://schema.org";
+  "@type": "FAQPage";
+  mainEntity: Array<{
+    "@type": "Question";
+    name: string;
+    acceptedAnswer: {
+      "@type": "Answer";
+      text: string;
+    };
+  }>;
+}
+
+export function buildFaqJsonLd(): FaqJsonLd {
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: FAQ_ITEMS.map((item) => ({
+      "@type": "Question",
+      name: item.question,
+      acceptedAnswer: {
+        "@type": "Answer",
+        text: item.answer,
+      },
+    })),
+  };
+}