Web App Agent Guide

Agent documentation for the Next.js web application (Peripheral).

How to Run

npm install
npm run dev          # Dev server at http://localhost:3000
npm run build        # Production build
npm run lint         # ESLint
npm run test         # Jest tests

Environment Variables

Required in .env.local:

NEVER commit secrets. Reference env var names only.

Agent Roles

1. Frontend Agent (Next.js / Mapbox / UI)

Scope: React components, Mapbox integration, Tailwind styling, ThemeContext.

Key Files:

• app/venezuela/page.tsx - Live article with map + timeline
• app/contexts/ThemeContext.tsx - Light/dark theme toggle
• app/layout.tsx - Root layout, Source Serif 4 font via next/font

Responsibilities:

• Modify UI components and styling
• Handle Mapbox marker interactions
• Manage edit mode for pin dragging
• Ensure hydration-safe rendering (see hydration-timezones skill)

2. Backend/API Agent

Scope: Next.js API routes, data shaping, response formatting.

Key Files:

• app/api/videos/[country]/route.ts - Fetch geolocated videos by country (primary)
• app/api/ice/videos/[country]/route.ts - Fetch videos by country (deprecated, backwards compatibility)
• app/api/stories/country/[country]/route.ts - Fetch stories by country
• app/api/video/[id]/position/route.ts - Update video coordinates
• app/api/admin/add-videos/route.ts - Insert videos (service role)
• app/api/admin/remove-video/route.ts - Search/delete videos

Responsibilities:

• Shape API responses for frontend consumption
• Handle query params (limit, offset, filters)
• Log requests for debugging
• Use appropriate Supabase client (server vs service)

3. Data / Supabase Operator

Scope: Database queries, migrations, data integrity.

Key Tables:

• video - Video metadata + coordinates (country, latitude, longitude)
• story - Clustered stories with title, summary, timestamps
• news_item - Individual news articles linked to stories
• entity_location - Location entities
• story_entity_location - Story-location join (rank=1 for primary)
• osint_source - Source metadata

Supabase Clients (lib/supabase/):

• server.ts - supabaseServer() - Uses SUPABASE_URL + SUPABASE_ANON_KEY
• client.ts - supabaseClient() - Uses NEXT_PUBLIC_* vars (browser)
• service.ts - createServiceClient() - Uses SERVICE_ROLE_KEY (writes)

Safety Rules:

1. Select before update - Always query first to verify record exists
2. DB writes only when explicitly requested - Never auto-commit changes
3. Use service client for writes - Only createServiceClient() has write perms
4. Log before/after - Log state before and after mutations

4. SEO / Editor Agent

Scope: Metadata, structured data, crawlability, SSR strategy.

Responsibilities:

• Add semantic HTML (article, header, time, etc.)
• Configure metadata in page exports
• Add JSON-LD structured data (NewsArticle/Article)
• Ensure SSR for critical content (client components affect indexing)
• Maintain sitemap.xml and robots.txt

Reference: See skills/seo-article-pages/SKILL.md

5. QA / Debug Agent

Scope: Hydration errors, timezone issues, regressions.

Common Issues:

• Hydration mismatch from locale-dependent date formatting
• Timezone drift between server/client
• Missing Mapbox token
• Stale video positions after edit mode

Reference: See skills/hydration-timezones/SKILL.md

Venezuela Episode Runbook

Video Data Flow

1. Source: Videos stored in video table with country='VE'
2. API: GET /api/videos/VE queries and transforms to VideoMarker[]
3. Fields: video_id, title, channel, published_date, latitude, longitude, public_url, source_url
4. Display: Mapbox markers with draggable pins in edit mode

Story Data Flow

1. Source: Stories linked via entity_location where name ilike 'venezuela'
2. API: GET /api/stories/country/venezuela?limit=200
3. Join Path: story -> story_entity_location (rank=1) -> entity_location
4. Frontend Pruning: Filtered by episode keywords (NOT database filtered)

Episode Keywords (Client-Side Pruning)

const episodeKeywords = [
  'venezuela', 'maduro', 'tanker', 'oil', 'blockade',
  'naval', 'ship', 'vessel', 'seize', 'capture',
  'strike', 'coast', 'fleet'
]

Stories are fetched with limit=200, then filtered client-side:

const filtered = stories.filter(s => {
  const haystack = `${s.title} ${s.summary}`.toLowerCase()
  return episodeKeywords.some(k => haystack.includes(k))
})

Do NOT modify the database to add pruning - keep filtering in frontend.

Timeline Computation

Location: app/venezuela/page.tsx lines 257-312

1. UTC Normalization: All dates converted to UTC midnight to avoid hydration mismatch
2. Day Bucketing: Videos + stories grouped by YYYY-MM-DD UTC key
3. Date Range: From earliest story/video to today (UTC)
4. Stacked Segments: Stories (lighter) stacked under videos (darker)
5. Click Behavior: Clicking a bar with videos triggers handleVideoClick(firstVideo)

const utcDate = new Date(Date.UTC(
  parsed.getUTCFullYear(),
  parsed.getUTCMonth(),
  parsed.getUTCDate()
))

Edit Mode

1. Toggle via edit button in header
2. Markers become draggable when editMode=true
3. Drags tracked in pendingChanges Map
4. Save button calls PATCH /api/video/[id]/position for each
5. After save, videos refetched to verify positions

Known Pitfalls

Quick Reference