Skip to Content
📚 MyStoryFlow Docs — Your guide to preserving family stories
Platform App (Web)

Platform App (Web App)

The Platform App is the main MyStoryFlow application where users create stories, record conversations, and design books.

Overview

The platform app (/apps/web-app) is built with:

  • Next.js 15 with App Router and React 19
  • Supabase for authentication, database, and storage
  • AI integrations: Anthropic Claude, OpenAI, and Google Gemini
  • Rich text editing: TipTap v2 with extensive extensions
  • Styling: Tailwind CSS 4
  • Payments: Stripe integration
  • Email: Resend for transactional emails

Application Architecture

Core Pages

  • / - Landing page with authentication
  • /dashboard - Main user dashboard
  • /stories - Story library and management
  • /campaigns - Book project management (collection campaigns)
  • /books - Book library, design, and publishing
  • /ai-conversations - AI-powered story capture with Elena
  • /voice-recording - Voice recording interface
  • /gallery - Media gallery for photos and recordings
  • /family - Family collaboration and sharing
  • /orders - Order management and tracking
  • /settings - User settings and preferences

Tech Stack Details

  • Frontend: React 19, Next.js 15, TypeScript
  • Editor: TipTap v2 with 20+ extensions including collaboration, tables, media, formatting
  • UI Components: Custom component library with Radix UI primitives
  • State Management: Zustand, React Query (TanStack Query)
  • Forms: React Hook Form with Zod validation
  • File Upload: FilePond with image processing
  • Analytics: Custom analytics package
  • PDF Generation: Sharp for image processing
  • Voice Processing: Integration with STT/TTS services

Key Features

🎙️ AI Conversations

The AI Conversations feature allows users to have natural conversations with Elena, an AI assistant that helps capture family stories.

Capabilities:

  • Voice recording with real-time transcription
  • AI-powered conversation guidance and prompts
  • Memory extraction and story generation
  • Conversation history and resume functionality
  • Multiple conversation sessions per campaign
  • Statistics tracking (total conversations, messages, duration)

Implementation:

  • /app/ai-conversations/page.tsx - Main conversation interface
  • /app/ai-conversations/[id]/page.tsx - Individual conversation view
  • /app/ai-conversations/history/page.tsx - Conversation history
  • Immersive conversation UI with error boundaries
  • WebSocket-based real-time transcription

📝 Story Creation & Editing

Story Library (/stories/page.tsx):

  • Comprehensive story management dashboard
  • Quick stats: total stories, word count, reading time, stories this week
  • Grid and list view modes
  • Search and filter by storyteller, status, date
  • Track story usage in books (chapter assignments)
  • Story cards with preview, edit, delete actions
  • Status tracking (draft, published)
  • Book integration - stories can be converted to book chapters

Rich Text Editor (TipTap-based):

  • 50+ editor components and extensions
  • Custom blocks and formatting
  • AI writing assistance integration
  • Real-time collaboration support
  • Template system with multiple story templates
  • Auto-save functionality
  • Performance optimizations with lazy loading
  • Keyboard shortcuts
  • Comments and inline annotations
  • Media embedding (images, videos, audio)
  • Table support
  • Code blocks with syntax highlighting

Editor Features:

  • /app/components/editor/EnhancedEditorShell.tsx - Main editor shell
  • /app/components/editor/hooks/useEditorExtensions.ts - Extension management
  • Custom plugins for story-specific features
  • Theme support for different book styles
  • Export capabilities

📚 Book Publishing

Book Library (/books/page.tsx):

  • Complete book management system
  • Statistics dashboard: total books, words, chapters, reading time, progress
  • Book status tracking (draft, designing, ready, published)
  • Progress bars showing completion percentage
  • Smart empty state that analyzes available content
  • Chapter management through story_ids array
  • Word count and chapter count tracking

Book Features:

  • Book creation and metadata management
  • Chapter organization (stories as chapters)
  • Design and layout tools
  • Cover creation system
  • Multiple book formats
  • Completion tracking
  • Publishing workflow
  • Order management integration

Implementation Details:

  • /app/books/[id]/page.tsx - Book detail view
  • /app/books/[id]/design/page.tsx - Book design interface
  • /app/books/[id]/chapters/page.tsx - Chapter management
  • /app/books/[id]/chapters/[chapterId]/edit/page.tsx - Chapter editor
  • Smart book editor with content blocks
  • Database: Uses books table with story_ids array for chapters

🎯 Campaign Management

Campaigns are book projects for collecting stories from storytellers (grandparents, parents, partners, etc.).

Campaign Dashboard (/campaigns/page.tsx):

  • Overview statistics: projects, stories, words, reading time
  • Goal progress tracking (default: 12 stories per campaign)
  • Status filtering (active, paused, completed, setup)
  • Top contributor tracking
  • Search and sort capabilities
  • Grid/list view modes

Campaign Features:

  • Create campaigns for different storytellers
  • Track relationship types (grandparent, parent, partner, other)
  • Monitor story collection progress
  • Set and track goals
  • Status management workflow
  • Story association and organization

Implementation:

  • /app/campaigns/page.tsx - Campaign listing
  • /app/campaigns/create/ - Campaign creation flow
  • /app/campaigns/[id]/ - Individual campaign view
  • Optimized queries to prevent N+1 problems
  • Enriched data with story counts and statistics

👨‍👩‍👧‍👦 Family Collaboration

Features:

  • Family member management
  • Shared galleries for photos and media
  • Family invitations system
  • Collaborative campaign participation
  • Shared story access

Gallery System (/gallery/page.tsx):

  • Media library for all user content
  • Photo, recording, and file management
  • Upload functionality
  • Browse and organize media
  • Integration with stories and books

🔐 Authentication & User Management

Authentication:

  • Email/password authentication
  • OAuth providers: Google, Apple, Facebook
  • Session management with Supabase
  • Role-based access control
  • Protected routes
  • Popup login for admin app integration

User Features:

  • User profile management
  • Settings and preferences
  • Billing and subscription management
  • Order history
  • Notification preferences

📱 Additional Features

Voice Recording:

  • Dedicated voice recording interface
  • Real-time audio capture
  • Transcription services
  • Recording history
  • Integration with conversations and stories

Orders & Billing:

  • Order creation and tracking
  • Payment processing with Stripe
  • Order confirmation pages
  • Invoice management
  • Subscription handling

Analytics:

  • Book analytics
  • Story statistics
  • Campaign progress tracking
  • User engagement metrics

Import System:

  • Import stories from external sources
  • Bulk import capabilities
  • Format conversion

Gift System:

  • Gift book purchases
  • Gift campaigns
  • No-signup gift flow

API Routes

The platform includes 35+ API route groups:

Core APIs:

  • /api/ai/* - AI integrations (Claude, OpenAI, Gemini)
  • /api/stories/* - Story CRUD operations
  • /api/campaigns/* - Campaign management
  • /api/books/* - Book operations
  • /api/conversation/* - Conversation handling
  • /api/conversations/* - Conversation management

Supporting APIs:

  • /api/auth/* - Authentication endpoints
  • /api/user/* - User management
  • /api/settings/* - User settings
  • /api/images/* - Image processing
  • /api/upload/* - File upload handling
  • /api/recordings/* - Voice recording management
  • /api/transcribe/* - Transcription services
  • /api/family/* - Family collaboration
  • /api/invoices/* - Billing and invoices
  • /api/analytics/* - Analytics data
  • /api/achievements/* - User achievements
  • /api/gifts/* - Gift system
  • /api/imports/* - Import functionality
  • /api/templates/* - Story templates

Component Architecture

Layout Components:

  • AppLayout - Main application layout
  • ConversationLayout - Conversation interface layout
  • Custom headers and footers for different contexts

Feature Components:

  • Editor: 55+ editor-specific components
  • Books: 13 book-related components
  • Dashboard: 11 dashboard widgets
  • UI Library: 45+ reusable UI components
  • Conversation: Conversation interface components
  • Family: Family collaboration components
  • Imports: Import flow components

Data Models

Primary Tables:

  • users - User accounts and profiles
  • campaigns - Book projects and storyteller relationships
  • stories - Story content (serves as chapters when in books)
  • books - Book metadata and configuration
  • conversations - AI conversation sessions
  • recordings - Voice recordings
  • families - Family groups and relationships
  • orders - Book orders and purchases

Note: The platform uses a stories model that serves dual purpose - standalone stories and book chapters. Books reference stories via the story_ids array field.

Configuration

Environment Variables:

  • Supabase configuration (URL, keys)
  • AI API keys (Anthropic, OpenAI, Gemini)
  • Stripe keys for payments
  • Email service configuration (Resend)
  • Storage configuration (Backblaze B2)
  • Analytics keys

Development Features

  • Comprehensive test suite (Jest, Playwright)
  • E2E testing infrastructure
  • Migration management system
  • Database seeding scripts
  • Template seeding
  • Development debugging panels
  • Performance monitoring tools
Research OverviewAdmin Dashboard