## Context

This change adds a light-weight, SEO-focused website to grow social discovery and conversions for:
- YouTube channel (`youtube.com/santhoshj`)
- Instagram (`@santhoshjanan`)
- Podcast ("Irregular Mind") on major platforms

The site needs to:
- Be fast and crawlable (SEO-first).
- Surface "latest" content and "high-performing" videos prominently on the home page.
- Provide clear CTAs to convert site visitors into followers/subscribers/listeners.
- Provide analytics (target: Umami) and event tracking to measure progress against 10% month-over-month goals.

Constraints and unknowns:
- Current repo appears to contain only OpenSpec artifacts (no existing website stack captured here yet).
- Instagram "dynamic" ingestion is constrained by Meta platform rules and API availability; we should plan for a fallback.
- "High-performing" requires a definition (views/likes/comments/watch-time) and may require YouTube Data API access.

## Goals / Non-Goals

**Goals:**
- Ship a static-first website architecture that is very fast, SEO-friendly, and easy to operate.
- Ingest content from YouTube + podcast RSS, and support Instagram via API where feasible or via embed/fallback.
- Provide a normalized content model usable by homepage modules (latest + featured/high-performing).
- Provide reusable CTAs with trackable outbound clicks and conversion measurement via Umami.
- Provide clear, testable SEO outputs: indexable pages, metadata, sitemap/robots, social sharing cards.

**Non-Goals:**
- Building a full CMS/editorial workflow (no admin UI in scope initially).
- Real-time updates (seconds/minutes). Near-real-time is not required; periodic refresh is acceptable.
- Complex personalization/recommendation engines.
- Replacing platform-native analytics; the goal is directional measurement for acquisition/conversion.

## Decisions

### 1) Static-first framework and deployment

**Decision:** Use a static-first site generator (Astro is the default recommendation) and deploy on linode instance over docker container.

**Rationale:** Static output maximizes performance and SEO while minimizing operational complexity. Astro provides great HTML-by-default output and only hydrates where necessary, keeping the "light-weight" premise intact.

**Alternatives considered:**
- Next.js: good ecosystem, but easier to accidentally ship heavier runtime/hydration than needed.
- Pure static HTML/manual: too brittle and hard to keep "dynamic" content updated.

### 2) Content ingestion model (build-time with scheduled refresh)

**Decision:** Fetch and normalize social content at build time (SSG) into a local data cache (JSON) that drives rendering. Refresh content on a schedule (cron) and on-demand (manual trigger).

**Rationale:** Keeps runtime simple and fast; avoids exposing API keys to the browser; avoids rate-limit issues on every pageview.

**Mechanics:**
- A build step runs `fetch-content` to produce a normalized dataset (e.g., `content/cache/*.json`).
- CI triggers rebuild on a schedule (e.g., hourly or daily) and after new uploads (manual trigger).

**Alternatives considered:**
- Runtime serverless fetch: more moving parts, harder caching story, slower page loads, and higher risk of API failures impacting the site.
- Client-side fetch: worst for SEO and exposes third-party dependence to users.

### 3) Sources and fallbacks (YouTube, Instagram, podcast)

**YouTube**
- **Decision:** Prefer YouTube Data API (v3) when available to obtain reliable metadata and performance stats (views/likes) for "high-performing".
- **Fallback:** Use the channel RSS feed to list latest videos if API keys are not available; in this mode, "high-performing" becomes manually curated or based on a static list.

**Instagram**
- **Decision:** Start with an embed-first approach for Instagram posts (oEmbed or platform embeds) and treat API-based ingestion as optional Phase 2.
- **Rationale:** Meta API access is frequently the longest pole (app review, token refresh, account type constraints). Embeds still allow reuse of posts without deep integration.

**Podcast**
- **Decision:** Use the podcast RSS feed as the canonical source; parse episodes into the normalized model. Link out to platform destinations (Apple/Spotify/etc).

### 4) Normalized content model and ranking

**Decision:** Define a unified content schema for the site (regardless of source), e.g.:
- `id`, `source` (`youtube|instagram|podcast`), `url`
- `title`, `description`, `publishedAt`
- `thumbnail`, `tags/categories`
- `metrics` (optional: `views`, `likes`, `comments`, `duration`)
- `featured` (manual override)

**High-performing definition:**
- Default: YouTube videos ranked by `views` (optionally recency-weighted), with a manual override list for editorial selection.
- Instagram and podcast "high-performing" starts as manual until reliable metrics are available.

### 5) Information architecture and SEO surface

**Decision:** Create a small set of indexable pages with stable URLs:
- `/` home (latest + featured/high-performing + channel highlights + CTAs)
- `/videos` (YouTube list/detail, or list only initially)
- `/podcast` (episode list)
- `/about` (channel/personal bio, links)

**SEO outputs:**
- Per-page metadata (title/description), canonical URLs
- Open Graph + Twitter cards
- `sitemap.xml` and `robots.txt`
- Structured data (`JSON-LD`) for Video/Podcast where appropriate

### 6) Conversion CTAs and event tracking

**Decision:** Implement CTAs as a reusable component that:
- Renders platform-specific primary actions (YouTube subscribe, Instagram follow, podcast listen)
- Uses outbound links that include UTM parameters
- Emits Umami events for `cta_click` with dimensions like `platform`, `placement`, `target`

### 7) Analytics (Umami) and measurement plan

**Decision:** Use Umami for pageviews + custom events.

**Events (initial):**
- `cta_click` (platform, placement)
- `outbound_click` (domain, placement)
- Optional: `video_play` / `episode_play` if embeds support reliable hooks (may be limited)

**Reporting targets:**
- Traffic by source (SEO vs social referrers)
- CTA click-through rate by placement
- Growth correlation: site referrals to channel follows (approximate; platform attribution is imperfect)

## Risks / Trade-offs

- [Instagram API complexity] → Start embed-first; treat API ingestion as optional and document requirements for later.
- [YouTube API keys / quotas] → Cache results; minimize calls; RSS fallback; allow manual "featured" list.
- [“High-performing” ambiguity] → Specify a clear initial metric (views) and allow manual overrides; refine after baseline data.
- [Stale content due to build-time fetch] → Scheduled rebuilds; manual trigger; show "Last updated" timestamp.
- [SEO requires real content depth] → Add dedicated indexable pages (videos/podcast/about) and ensure metadata + structured data are correct.
- [Analytics privacy expectations] → Keep tracking minimal; avoid PII; document what is tracked.

## Migration Plan

1. Implement the static-first site skeleton and deploy a minimal version (home + about + analytics).
2. Add ingestion for podcast RSS and YouTube (RSS first, upgrade to API when keys are available).
3. Add homepage modules (latest + featured/high-performing) and CTA placements.
4. Add SEO hardening (sitemap/robots/canonicals/structured data) and validate indexing.
5. Add Instagram embed module (and/or API ingestion if chosen).
6. Iterate on ranking and content presentation based on Umami data.

Rollback:
- Revert deploy to previous static build; ingestion failures should fail closed (serve last good cached dataset).

## Open Questions

- Hosting target: Cloudflare Pages vs Netlify vs Vercel (affects cron/rebuild approach and any serverless options).
- Do you want a custom domain (and which), and should the site target a personal brand name vs channel name?
- Is a YouTube Data API key available, or should we start with RSS-only for v1?
- Should Instagram be embed-only for v1, or do you want to pursue API ingestion (which may require a business account/app setup)?
- Preferred measurement: which CTAs matter most (YouTube subs vs Instagram follows vs podcast listens) and where should they be placed (hero, sticky, end of sections)?