app-map.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Threads Insight Pipeline — App Map</title>
  <style>
    :root {
      --bg: #090d16;
      --card-bg: #0f172a;
      --border: #1e293b;
      --text: #f1f5f9;
      --muted: #94a3b8;
      --sky: #38bdf8;
      --emerald: #34d399;
      --amber: #fbbf24;
      --indigo: #818cf8;
    }
    * { box-sizing: border-box; margin: 0; padding: 0; }
    body {
      background: var(--bg);
      color: var(--text);
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
      line-height: 1.6;
      padding: 2.5rem 1.5rem;
    }
    .container {
      max-width: 860px;
      margin: 0 auto;
    }
    header {
      border-bottom: 1px solid var(--border);
      padding-bottom: 1.5rem;
      margin-bottom: 2rem;
    }
    h1 {
      font-size: 1.75rem;
      font-weight: 700;
      color: var(--text);
      margin-bottom: 0.5rem;
    }
    .subtitle {
      color: var(--muted);
      font-size: 0.95rem;
    }
    .badge {
      display: inline-block;
      font-family: ui-monospace, monospace;
      font-size: 0.75rem;
      padding: 0.2rem 0.5rem;
      border-radius: 4px;
      border: 1px solid var(--border);
      background: #1e293b80;
      color: var(--sky);
      margin-top: 0.5rem;
    }
    section {
      background: var(--card-bg);
      border: 1px solid var(--border);
      border-radius: 8px;
      padding: 1.5rem;
      margin-bottom: 1.75rem;
    }
    h2 {
      font-size: 1.15rem;
      font-weight: 600;
      color: var(--text);
      margin-bottom: 1rem;
      display: flex;
      align-items: center;
      gap: 0.5rem;
    }
    p, li {
      color: var(--muted);
      font-size: 0.9rem;
      margin-bottom: 0.75rem;
    }
    ul { list-style-position: inside; }
    code {
      font-family: ui-monospace, monospace;
      font-size: 0.85rem;
      background: #020617;
      border: 1px solid var(--border);
      padding: 0.15rem 0.4rem;
      border-radius: 4px;
      color: var(--sky);
    }
    pre {
      background: #020617;
      border: 1px solid var(--border);
      border-radius: 6px;
      padding: 1rem;
      overflow-x: auto;
      font-family: ui-monospace, monospace;
      font-size: 0.825rem;
      color: var(--text);
      margin-top: 0.75rem;
      margin-bottom: 0.75rem;
    }
    .diagram-container {
      width: 100%;
      background: #020617;
      border: 1px solid var(--border);
      border-radius: 6px;
      padding: 1rem;
      margin: 1rem 0;
      display: flex;
      justify-content: center;
    }
    svg text {
      font-family: ui-monospace, monospace;
    }
    .route-stop {
      border-left: 2px solid var(--sky);
      padding-left: 1rem;
      margin-bottom: 1.25rem;
    }
    .route-stop strong {
      color: var(--text);
      display: block;
      margin-bottom: 0.25rem;
    }
    .practice-box {
      border-left: 3px solid var(--emerald);
      background: #064e3b20;
      padding: 1rem;
      border-radius: 4px;
      margin-top: 0.5rem;
    }
    .practice-box strong { color: var(--emerald); }
  </style>
</head>
<body>
  <div class="container">
    <header>
      <h1>Threads Insight Pipeline — App Map</h1>
      <p class="subtitle">Reference architecture, data flow, and key code locations for the completed proof of concept.</p>
      <span class="badge">Next.js 15 • TypeScript • Gemini 2.5 Flash • Zod Validation</span>
    </header>

    <!-- Overview -->
    <section>
      <h2>System Overview</h2>
      <p>
        <strong>Threads Insight Pipeline</strong> ingests raw scraped Meta Threads posts (rife with slang, emojis, handles, and hashtags), runs strict PII sanitation, assigns topic classifications, and infers demographic signals (Age Group &amp; Gender). Ambiguous posts are isolated as &ldquo;Unspecified&rdquo; outliers so that aggregate percentage calculations remain mathematically sound.
      </p>

      <div class="diagram-container">
        <svg viewBox="0 0 760 160" width="100%" height="160" xmlns="http://www.w3.org/2000/svg">
          <!-- Boxes -->
          <rect x="10" y="30" width="140" height="90" rx="6" fill="#0f172a" stroke="#38bdf8" stroke-width="1.5" />
          <text x="80" y="65" fill="#f1f5f9" font-size="12" font-weight="bold" text-anchor="middle">Input Workbench</text>
          <text x="80" y="85" fill="#94a3b8" font-size="10" text-anchor="middle">Pre-validation</text>
          <text x="80" y="100" fill="#94a3b8" font-size="9" text-anchor="middle">src/components/Input...</text>

          <!-- Arrow 1 -->
          <line x1="150" y1="75" x2="200" y2="75" stroke="#64748b" stroke-width="2" />
          <polygon points="200,75 192,70 192,80" fill="#64748b" />

          <!-- Box 2 -->
          <rect x="200" y="30" width="160" height="90" rx="6" fill="#0f172a" stroke="#818cf8" stroke-width="1.5" />
          <text x="280" y="65" fill="#f1f5f9" font-size="12" font-weight="bold" text-anchor="middle">POST /api/extract</text>
          <text x="280" y="85" fill="#818cf8" font-size="10" text-anchor="middle">Gemini 2.5 Flash</text>
          <text x="280" y="100" fill="#94a3b8" font-size="9" text-anchor="middle">PII Sanitization</text>

          <!-- Arrow 2 -->
          <line x1="360" y1="75" x2="410" y2="75" stroke="#64748b" stroke-width="2" />
          <polygon points="410,75 402,70 402,80" fill="#64748b" />

          <!-- Box 3 -->
          <rect x="410" y="30" width="150" height="90" rx="6" fill="#0f172a" stroke="#34d399" stroke-width="1.5" />
          <text x="485" y="65" fill="#f1f5f9" font-size="12" font-weight="bold" text-anchor="middle">Zod &amp; Metrics</text>
          <text x="485" y="85" fill="#34d399" font-size="10" text-anchor="middle">Outlier Isolation</text>
          <text x="485" y="100" fill="#94a3b8" font-size="9" text-anchor="middle">src/lib/metrics.ts</text>

          <!-- Arrow 3 -->
          <line x1="560" y1="75" x2="610" y2="75" stroke="#64748b" stroke-width="2" />
          <polygon points="610,75 602,70 602,80" fill="#64748b" />

          <!-- Box 4 -->
          <rect x="610" y="30" width="140" height="90" rx="6" fill="#0f172a" stroke="#fbbf24" stroke-width="1.5" />
          <text x="680" y="65" fill="#f1f5f9" font-size="12" font-weight="bold" text-anchor="middle">Analytics Dashboard</text>
          <text x="680" y="85" fill="#fbbf24" font-size="10" text-anchor="middle">12-Column Grid</text>
          <text x="680" y="100" fill="#94a3b8" font-size="9" text-anchor="middle">Copyable JSON</text>
        </svg>
      </div>
    </section>

    <!-- Code Route -->
    <section>
      <h2>Key Code Locations (Reference Route)</h2>
      
      <div class="route-stop">
        <strong>1. User Input &amp; Pre-Validation: <code>src/components/InputWorkbench.tsx</code></strong>
        <p>Houses the textarea, live character counter, &ldquo;Load Sample Scraped Data&rdquo; handler, and client-side empty-input alert that catches blank submissions before network calls.</p>
      </div>

      <div class="route-stop">
        <strong>2. Server-Side Extraction &amp; PII Scrubbing: <code>src/app/api/extract/route.ts</code> &amp; <code>src/lib/gemini.ts</code></strong>
        <p>Route handler invoking Google Gemini 2.5 Flash with structured output mode. Strips usernames, emails, and phone numbers from raw text, assigns topic categories, and infers age/gender signals.</p>
      </div>

      <div class="route-stop">
        <strong>3. Statistical Outlier Math: <code>src/lib/metrics.ts</code></strong>
        <p>Calculates topic distribution percentages across all posts, but filters out &ldquo;Unspecified&rdquo; demographic posts from the base denominator—tracking them as dedicated outlier counters to keep identified percentages mathematically accurate.</p>
      </div>

      <div class="route-stop">
        <strong>4. Dashboard Visualization &amp; Export: <code>src/components/AnalyticsOverview.tsx</code> &amp; <code>JsonOutputViewer.tsx</code></strong>
        <p>Renders progress bars, summary cards, and the 1-click clipboard export with visual confirmation.</p>
      </div>
    </section>

    <!-- To change this -->
    <section>
      <h2>To Change This, Start Here</h2>
      <ul>
        <li><strong>Add or rename topic categories:</strong> Update <code>CategoryEnum</code> in <code>src/lib/schemas.ts</code> and update the category taxonomy prompt in <code>src/lib/gemini.ts</code>.</li>
        <li><strong>Add more realistic sample posts:</strong> Edit <code>SAMPLE_THREADS_RAW_TEXT</code> in <code>src/data/sampleThreadsData.ts</code>.</li>
        <li><strong>Configure live Gemini API key:</strong> Add <code>GEMINI_API_KEY=your_key</code> to <code>.env.local</code>. (The app gracefully uses its built-in engine if no key is supplied).</li>
      </ul>
    </section>

    <!-- Reusable Practice -->
    <section>
      <h2>A Practice to Reuse</h2>
      <div class="practice-box">
        <strong>Strict Schema Contracts + Explicit Outlier Isolation</strong>
        <p style="margin-top: 0.5rem; color: #cbd5e1;">
          When processing uncurated real-world text with LLMs, always separate <em>detection certainty</em> from <em>aggregate metrics</em>. By explicitly enforcing an &ldquo;Unspecified&rdquo; state in your Zod schema and excluding those records from the base denominator in <code>src/lib/metrics.ts</code>, you prevent sparse or ambiguous posts from mathematically skewing your analytical findings.
        </p>
      </div>
    </section>

    <!-- How to Run -->
    <section>
      <h2>How to Run</h2>
      <pre># Start development server
npm run dev

# Or build for production
npm run build && npm run start</pre>
      <p style="font-size: 0.8rem; color: var(--muted); margin-top: 0.5rem;">
        Open <code>http://localhost:3000</code> in your browser.
      </p>
    </section>
  </div>
</body>
</html>