149 lines
8.1 KiB
Markdown
149 lines
8.1 KiB
Markdown
## 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)?
|