RelNotes Studio

Developer

Original Idea

Release Notes Generator A web app that pulls PRs, drafts release notes, and opens a review flow.

Product Requirements Document: RelNotes Studio

1. Executive Summary

RelNotes Studio is a high-performance AI SaaS platform designed to automate the bridge between engineering output and stakeholder communication. By integrating directly with Version Control Systems (VCS) like GitHub and GitLab, the platform fetches Pull Request (PR) data, applies a multi-stage AI reasoning pipeline (GPT-4o) to summarize technical changes into business value, and provides a collaborative, real-time environment for Product Managers and Engineers to refine and approve release notes. Built on the 2026 cutting-edge "Server-First" stack, RelNotes Studio ensures enterprise-grade security, instantaneous UI responsiveness, and seamless multi-channel distribution.

2. Problem Statement

The manual process of distilling technical Pull Requests into readable, high-impact release notes is a significant bottleneck in the software development lifecycle. Engineers often write PR descriptions for other engineers, making them opaque to business stakeholders. Conversely, Product Managers spend hours chasing context across Jira, Linear, and GitHub. This misalignment leads to delayed communications, missed features in announcements, and a lack of transparency regarding the ROI of engineering efforts.

3. Goals & Success Metrics

  • Efficiency: Reduce the average time to draft a release note from 2 hours to under 10 minutes.
  • Consistency: Achieve a 90% "Human-Approval Rate" for AI-generated summaries without major edits.
  • Engagement: Increase stakeholder read rates of release notes by 40% through better "Business Value" framing.
  • Technical Health: Maintain <100ms Time-to-First-Token (TTFT) for AI streaming and 99.9% uptime.

4. User Personas

  • Product Manager (PM): Needs to translate technical "mumbo-jumbo" into customer-facing benefits and ensure branding is consistent.
  • Software Engineer: Wants to provide technical context quickly without writing long-form prose or leaving their workflow.
  • Release Engineer: Focuses on the accuracy of the versioning and ensuring all merged code is accounted for.
  • Technical Writer: Oversees the tone, voice, and documentation standards across the organization.

5. User Stories

  • As a PM, I want to select a date range or tag so that I can automatically pull all relevant PRs for our bi-weekly release.
  • As an Engineer, I want the system to fetch my Jira/Linear ticket context so that the AI understands the "Why" behind my code changes.
  • As a Stakeholder, I want to receive a branded PDF or Slack notification so that I stay informed about product progress without checking GitHub.
  • As a Security Lead, I want VCS tokens to be encrypted at the application layer so that our source code access remains secure.

6. Functional Requirements

6.1 VCS Integration & Data Fetching

  • GitHub App Protocol: Use GitHub Apps for fine-grained permissions and short-lived tokens (1-hour expiry).
  • Freeze-at-Merge Pattern: Automatically fetch Jira/Linear ticket context at the moment of PR merge and store a machine-readable JSON snapshot in the PR body.

6.2 AI Summarization Pipeline (GPT-4o)

  • Multi-Stage Prompting:
    • Stage 1: Technical Extraction (Diff analysis).
    • Stage 2: Impact Mapping (Business value translation).
    • Stage 3: Executive Synthesis (Final draft generation using R-TCC-COE framework).
  • Streaming Output: Real-time text generation via Vercel AI SDK 6.0.

6.3 Collaborative Editor

  • Tiptap + Liveblocks: A headless WYSIWYG editor with real-time cursor tracking and range-based commenting.
  • Markdown Support: Full import/export capability for Markdown syntax.

6.4 Approval Workflow

  • State Machine: Immutable states (DRAFT → INTERNAL_REVIEW → STAKEHOLDER_APPROVAL → PUBLISHED).
  • Side-by-Side Diffing: Visual comparison between draft versions.

6.5 Distribution & Branding

  • Branded Exports: PDF and HTML generation using react-pdf-tailwind (v4) and Fileforge.
  • Webhook Distribution: Automated announcements to Slack and Discord.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

  • Framework: Next.js 16.1.3 (Stable Turbopack, React 19.2).
  • Styling: Tailwind CSS v4 (CSS-variable-first).
  • Database: PostgreSQL 17 (Supabase) with Range/Hash Partitioning for multi-tenancy.
  • ORM: Prisma 7 with Client Extensions for transparent field-level encryption.
  • AI: Vercel AI SDK 6.0 with GPT-4o.
  • Infrastructure: Vercel with Partial Prerendering (PPR) and Fluid Compute.

7.2 Architecture Patterns

  • "use cache" Directive: Explicit per-component caching for repository metadata.
  • Agentic UI: Structured outputs via Zod schemas and generateObject for type-safe UI components.
  • Background Processing: Inngest for durable AI workflows to handle LLM wait times without incurring Vercel idle costs.

7.3 Security

  • Envelope Encryption: Use AWS KMS or HashiCorp Vault to manage Data Encryption Keys (DEKs) for VCS tokens.
  • AES-256-GCM: Non-deterministic encryption for all sensitive fields in PostgreSQL.

8. Data Model

Entity: Project

  • id: UUID (PK)
  • tenant_id: UUID (Indexed)
  • vcs_provider: Enum (GITHUB, GITLAB)
  • installation_id: String (Encrypted)
  • config: JSONB (Branding, templates)

Entity: ReleaseNote

  • id: UUID (PK)
  • project_id: UUID (FK)
  • status: Enum (DRAFT, PENDING, PUBLISHED)
  • current_version_id: UUID (FK to ReleaseNoteVersion)
  • tag_range: String (e.g., "v1.2.0...v1.3.0")

Entity: PR_Snapshot

  • id: UUID (PK)
  • release_id: UUID (FK)
  • external_id: String (GitHub PR Number)
  • metadata_snapshot: JSONB (Frozen ticket data, diff summary)

9. API Specification

POST /api/release/generate

  • Purpose: Triggers the multi-stage AI summary.
  • Request: { projectId: string, base: string, head: string }
  • Response: ReadableStream (AI text)

PATCH /api/release/status

  • Purpose: Transition a release note through the workflow.
  • Request: { noteId: string, action: 'APPROVE' | 'REQUEST_CHANGES', comment?: string }
  • Security: Requires RBAC check via authedAction wrapper.

10. UI/UX Requirements

  • Dashboard: Use PPR to stream in "Recent Releases" while the sidebar shell remains static.
  • The "Review Inbox": A unified view for users with pending approval tasks.
  • Progressive Stepper: A visual indicator of the approval stages at the top of the editor.
  • Optimistic UI: Use React useOptimistic for state transitions to ensure a zero-latency feel.

11. Non-Functional Requirements

  • Performance: All dashboard pages must achieve a Lighthouse Performance score of 95+.
  • Accessibility: WCAG 2.1 AA compliant.
  • Compliance: SOC2 Type II compliant data handling (Encryption-at-rest/in-transit).
  • Scalability: Database sub-partitioning by tenant_id to support 10k+ enterprise tenants.

12. Out of Scope

  • Direct code editing or commit capabilities.
  • Integration with legacy self-hosted SVN/Mercurial.
  • Automated deployment/CI/CD triggering.

13. Risks & Mitigations

  • Risk: AI hallucinations in technical summaries.
    • Mitigation: "Human-in-the-loop" mandatory review; AI includes citations/links to specific PRs for verification.
  • Risk: VCS API Rate Limits.
    • Mitigation: Upstash Redis caching layer for all non-sensitive metadata.
  • Risk: Token Exposure.
    • Mitigation: Short-lived GitHub App installation tokens; zero storage of plaintext tokens.

14. Implementation Tasks

Phase 1: Project Setup & Foundation

  • [ ] Initialize Next.js 16.1.3 project with Turbopack
  • [ ] Configure Tailwind CSS v4 and standard theme variables
  • [ ] Set up Supabase (PostgreSQL 17) and Prisma 7
  • [ ] Implement Application-Layer Encryption (ALE) logic for tokens
  • [ ] Configure NextAuth.js with GitHub App provider

Phase 2: VCS & Context Fetching

  • [ ] Build GitHub App installation flow
  • [ ] Implement PR fetching logic with "Freeze-at-Merge" Jira/Linear regex
  • [ ] Create PR_Snapshot table and persistence logic
  • [ ] Implement background sync via Inngest for repository metadata

Phase 3: AI Engine & Summarization

  • [ ] Implement multi-stage GPT-4o prompt chaining using Vercel AI SDK 6.0
  • [ ] Add streamText support for real-time summary generation
  • [ ] Build the "R-TCC-COE" prompt template system
  • [ ] Configure Inngest step.ai.infer() to handle long-running LLM calls

Phase 4: Collaborative Editor & Workflow

  • [ ] Integrate Tiptap editor with Markdown extensions
  • [ ] Implement real-time collaboration with Liveblocks (Yjs)
  • [ ] Build range-based commenting and notification system
  • [ ] Create the state machine for multi-stage approvals using Server Actions
  • [ ] Add side-by-side diffing for ReleaseNoteVersions

Phase 5: Distribution & Polish

  • [ ] Build branded PDF export using react-pdf-tailwind
  • [ ] Implement Fileforge API for high-fidelity HTML/PDF renders
  • [ ] Set up Slack/Discord webhook integration
  • [ ] Implement Partial Prerendering (PPR) on the main dashboard
  • [ ] Final security audit and SOC2 documentation prep