This commit is contained in:
@@ -0,0 +1,148 @@
|
||||
## 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)?
|
||||
Reference in New Issue
Block a user