astro-website/openspec/changes/archive/2026-02-10-dynamic-homepage-social-acquisition/design.md

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)?