be-my-anchor/docs/prd.md

Product Requirements Document (PRD): Be My Anchor

Status: Approved (Post Grill-Me)
Target Version: 2.0 (Full Refactor)
Architecture: TypeScript / Node.js Fullstack
Primary Output: docs/prd.md

---

1. Executive Summary & Vision

Be My Anchor transforms written materials—technical blogs, research papers, news articles, novels, and documentation—into an engaging, listening-first multimedia experience.

Rather than relying on brittle, heavy web scrapers or monotone text-to-speech readers, Be My Anchor adopts an API-first ingestion model combined with:

1. High-Fidelity Audio Generation: Seamless multi-provider TTS (Edge TTS, OpenAI, ElevenLabs) with smart text chunking and audio stitching.
2. Hearing-Front Content Adaptation: An LLM-powered scriptwriting engine that adapts dense text into conversational spoken formats (e.g., Feynman-style technical breakdown or 2-host conversational dialogue).
3. Synchronized Visual Companion: A web player that dynamically surfaces referenced figures, diagrams, and code snippets in sync with the audio narration.

---

2. Core Philosophy & Phased Strategy

┌─────────────────────────────────────────────────────────────┐
│ Phase 1: Robust Audio Generation Core                       │
│ - Multi-provider TTS (Edge TTS, OpenAI, ElevenLabs)         │
│ - Long-form text chunking & audio stitching                 │
│ - Basic web player & episode library                        │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Phase 2: Hearing-Front Content Transformation               │
│ - "Feynman" Deep-Dive Presenter Persona                     │
│ - Dual-Host Dialogue Persona (NotebookLM style)             │
│ - Script stage cue tagging                                  │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Phase 3: Interactive Synchronized Multimedia Player         │
│ - Timestamped visual cues (figures, code, diagrams)         │
│ - Karaoke-style synced transcript                           │
│ - Stage-aware responsive visual pane                        │
└─────────────────────────────────────────────────────────────┘

---

3. User Personas & Modes of Operation

Persona 1: The Engineer / Researcher ("The Feynman Mode")

• Content: Technical architecture posts, RFCs, research papers, algorithm deep-dives.
• Narrator Style: A world-class communicator (like Richard Feynman or a top tech lead) explaining concepts using intuitive analogies, breaking down equations, and explaining diagrams.
• Visual Need: When the narrator says "Looking at Figure 2, the ingress traffic routes through...", Figure 2 automatically appears on screen.

Persona 2: The Informed Professional ("The Dual-Host Dialogue")

• Content: Industry news, opinion pieces, market shifts, newsletters.
• Narrator Style: Two AI co-hosts bantering, asking each other rhetorical questions, and adding contextual background not directly present in the source article.
• Visual Need: Highlight cards, quotes, and source citations appearing on the dashboard.

Persona 3: The Audiobook / Direct Listener ("Verbatim Mode")

• Content: Novels, essays, speeches, narrative non-fiction.
• Narrator Style: Clear, expressive single-narrator audiobook delivery with sentence-by-sentence paragraph tracking.

---

4. System Architecture

                      ┌────────────────────────────┐
                      │    API Ingestion Endpoint  │
                      │ (Markdown / Text / Assets) │
                      └─────────────┬──────────────┘
                                    │
                                    ▼
                      ┌────────────────────────────┐
                      │ Hearing-Front Script Engine│
                      │   (LLM: OpenAI / Claude)   │
                      │  - Rewrites text for ear   │
                      │  - Generates Stage Cues    │
                      └─────────────┬──────────────┘
                                    │
                         Script with Stage Marks
                                    │
                                    ▼
                      ┌────────────────────────────┐
                      │    TTS Generation Core     │
                      │ ┌──────────┐ ┌───────────┐ │
                      │ │ Edge TTS │ │OpenAI TTS │ │
                      │ └──────────┘ └───────────┘ │
                      │ ┌────────────────────────┐ │
                      │ │ ElevenLabs (Multi-Voice│ │
                      │ └────────────────────────┘ │
                      │ - Chunker & Audio Stitcher │
                      │ - Timing Aligner (VTT/JSON)│
                      └─────────────┬──────────────┘
                                    │
                                    ▼
┌───────────────────────────────────┴───────────────────────────────────┐
│                           Data & Storage                              │
│  - Database: Prisma ORM (MongoDB / PostgreSQL)                        │
│  - File Storage: Local static / S3-compatible (Audio MP3s & Figures)  │
└───────────────────────────────────┬───────────────────────────────────┘
                                    │
                                    ▼
┌───────────────────────────────────────────────────────────────────────┐
│                 Interactive Web Player (Next.js / TS)                 │
│  ┌───────────────────────┐ ┌───────────────────────────────────────┐  │
│  │    Audio Player UI    │ │       Synchronized Visual Stage       │  │
│  │  - Waveform / Scrubber│ │  - Figures / Diagrams from post       │  │
│  │  - Speed / ±15s Skips │ │  - Syntax-highlighted code snippets   │  │
│  │  - Live Transcript    │ │  - Key takeaway summary cards         │  │
│  └───────────────────────┘ └───────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────┘

---

5. Functional Requirements

5.1 Content Ingestion (API-Driven)

• Provide a clean REST API accepting:
  • title: String
  • content: Plain text or Markdown (including image references ![alt](url))
  • format_mode: 'feynman' | 'dual_host' | 'verbatim'
  • voice_config: Provider preference (edge | openai | elevenlabs), voice IDs, speed
  • supplemental_materials: Optional array of images/figures, captions, and links
• No requirement for headless Selenium or browser dependencies on the server.

5.2 Hearing-Front Content Transformation

• Verbatim Cleaner: Strips markdown artifacts, normalizes punctuation, phonetic hints for acronyms.
• Feynman Script Generator:
  • Rewrites technical content into an oral lecture/walkthrough.
  • Generates [STAGE: figure_id] or [STAGE: code_block_id] inline tags corresponding to visual assets.
• Dual-Host Dialogue Generator:
  • Turns article content into an interactive conversation between Host A (e.g., inquisitive, relatable) and Host B (e.g., domain expert).
  • Emits speaker-tagged lines: SpeakerA: ... and SpeakerB: ....

5.3 TTS Engine & Audio Processing

• Provider Abstraction Interface (ITextToSpeechProvider):
  • EdgeTTSProvider: Free, instant, high-quality neural voices (en-US-ChristopherNeural, en-US-JennyNeural, etc.), zero API key required.
  • OpenAITTSProvider: alloy, echo, fable, onyx, nova, shimmer.
  • ElevenLabsProvider: High-fidelity multi-voice assignment with voice cloning or distinct character voices for multi-host dialogue.
• Long-Text Chunker:
  • Breaks script into sentence/clause chunks respecting provider character limits (e.g. 4096 chars).
  • Handles speaker switching in dual-host mode without awkward pauses.
• Audio Stitcher & Aligner:
  • Stitches chunk audio files into a unified master .mp3.
  • Outputs a timing manifest (timings.json or WebVTT) recording the start and end timestamp of each paragraph, speaker turn, and stage marker.

5.4 Synchronized Web View & Media Player

• Episode Library:
  • List of generated episodes with duration, creation date, mode, and status (processing, ready, failed).
• Audio Player Controls:
  • Play / Pause, Progress scrubber, Current time / Total duration.
  • Jump Back 15s (-15s), Jump Forward 15s (+15s).
  • Playback speed selection (0.8x, 1.0x, 1.25x, 1.5x, 2.0x).
• Synchronized Transcript Pane:
  • Interactive transcript that auto-scrolls and highlights the active paragraph/dialogue turn as audio plays.
  • Clicking any paragraph seeks playback directly to that timestamp.
• Synchronized Stage (Supplemental Visual Information):
  • Responsive visual viewport alongside or above the player.
  • When the audio reaches a tagged stage (e.g. timestamp 02:15):
    • Automatically displays the relevant figure, architecture diagram, equation, or code snippet.
    • Provides zoom/expand view for detailed inspection.
    • Gracefully transitions to summary notes when no specific figure is active.

---

6. Data Model (Prisma Schema Specification)

datasource db {
  provider = "postgresql" // or "mongodb"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

enum ProcessingStatus {
  PENDING
  SCRIPTING
  SYNTHESIZING
  READY
  FAILED
}

enum ScriptMode {
  VERBATIM
  FEYNMAN
  DUAL_HOST
}

model Episode {
  id              String           @id @default(cuid()) @map("_id")
  title           String
  originalContent String
  scriptContent   String?
  mode            ScriptMode       @default(FEYNMAN)
  status          ProcessingStatus @default(PENDING)
  durationSeconds Float?
  audioUrl        String?
  timingsJson     String?          // Serialized timestamp cues
  
  stages          StageItem[]
  createdAt       DateTime         @default(now())
  updatedAt       DateTime         @updatedAt
}

model StageItem {
  id              String   @id @default(cuid()) @map("_id")
  episodeId       String
  timestampSeconds Float
  type            String   // "IMAGE" | "CODE" | "CALLOUT"
  title           String?
  content         String   // Image URL or Code snippet / Callout text
  caption         String?
  
  episode         Episode  @relation(fields: [episodeId], references: [id], onDelete: Cascade)
}

---

7. API Specification

POST /api/episodes

Creates a new conversion job.

{
  "title": "Understanding Kubernetes Ingress Controllers",
  "content": "# Markdown content...",
  "mode": "FEYNMAN",
  "ttsProvider": "edge",
  "voiceOptions": {
    "primaryVoice": "en-US-ChristopherNeural",
    "speed": 1.0
  },
  "visualAssets": [
    {
      "id": "fig-1",
      "type": "IMAGE",
      "url": "https://example.com/arch.png",
      "caption": "Figure 1: Ingress routing architecture"
    }
  ]
}

Response: 202 Accepted with { "episodeId": "clx...", "status": "PENDING" }.

GET /api/episodes/:id

Retrieves episode details, audio URL, processing status, transcript timings, and stage markers.

GET /api/episodes

Lists all generated episodes for the library view.

---

8. Technical Stack

Component	Technology	Rationale
Runtime & Language	Node.js (v20+) / TypeScript	Rapid prototyping, strong typing, zero Python venv/setup friction.
Framework	Next.js (App Router)	Unified backend API routes + reactive frontend player in one repo.
Database & ORM	Prisma + MongoDB or PostgreSQL	Lightweight document/relational storage matching user preference.
Audio Generation	msedge-tts, OpenAI API, ElevenLabs SDK	Free zero-key tier (Edge) + premium commercial options.
Audio Processing	fluent-ffmpeg or Web Audio APIs	Fast server-side audio stitching and silence injection.
LLM Orchestration	Vercel AI SDK / OpenAI SDK	Streaming script generation and structured stage extraction.
Styling	Tailwind CSS / Lucide Icons	Clean modern aesthetic, responsive audio controls.

---

9. Implementation Roadmap

Phase 1: Core Audio Generation & Minimal Player (Week 1)

• Initialize Next.js + TypeScript project structure and Prisma configuration.
• Implement ITextToSpeechProvider interface with EdgeTTSProvider and OpenAITTSProvider.
• Build audio chunking, concatenation, and static file delivery.
• Implement basic Web Player UI (Play/Pause, Scrubber, Episode list).

Phase 2: Hearing-Front Script Engine (Week 2)

• Implement prompt templates for:
  • Feynman Master Presenter (single host, conversational breakdown).
  • Dual-Host Dialogue (speaker-tagged turns).
• Parse speaker tags and route chunks to distinct voices in the TTS pipeline.
• Output synchronized paragraph/sentence timestamp manifests.

Phase 3: Synchronized Visual Stages (Week 3)

• Extract or link visual assets (figures/diagrams/code) to script stages.
• Build the interactive Stage Viewer in the web player:
  • Figure transitions locked to audio progress.
  • Interactive transcript with click-to-seek.
• End-to-end testing with technical papers, blog posts, and news feeds.