MyStoryFlow UX & Architecture Roadmap v1.1

Document Version: 1.1 Last Updated: 2025-01-29 Status: Active

Document Purpose

This document serves as the single source of truth for MyStoryFlow’s user experience and architecture evolution. It combines findings from:

• Comprehensive codebase architecture analysis
• Database schema review
• UX/UI navigation and flow assessment
• Industry competitor research (StoryWorth, Reedsy, Blurb, Mixbook, LifeTales)
• Collaborative decision-making sessions

IMPORTANT: Before making any changes to the application, consult this document to ensure alignment with the established roadmap.

Executive Summary

The Core Problem

MyStoryFlow has accumulated organizational debt from multiple rounds of feature additions:

• 7 navigation sections with 20+ items (overwhelming for seniors)
• 4 different content creation paths (confusing entry points)
• 3 overlapping book-related pages (Book Projects vs Books vs Book Designer)
• Story → Chapter → Book complexity (one layer too many)

The Solution: Story = Chapter

After extensive analysis and competitor research, we’ve determined that the industry standard is Story = Chapter:

BEFORE: Voice → Conversation → Story → Chapter → Book (5 layers)
AFTER:  Voice/Conversation → Story → Book (3 layers)

Key Principle: A story IS a chapter. When you add a story to a book, it becomes a chapter. Books are simply ordered collections of stories.

Our Competitive Advantage

Unlike competitors, MyStoryFlow offers:

1. Voice-First Creation - Talk naturally, we transcribe and enhance
2. AI Conversation Partner (Elena) - Guided story extraction through dialogue
3. Original Voice Preservation - Digital book includes audio artifacts
4. Family Collaboration - Multiple family members can contribute and edit
5. Rich TipTap Editor - Professional editing with progressive disclosure

Core Simplification: Story = Chapter

The Decision

Problem: The current architecture has Stories, which become Chapters, which go into Books. This creates:

• User confusion (“Is my story a chapter?”)
• Duplicate content (story content copied to chapter content)
• Complex linking (book_chapters can reference story_id, conversation_id, OR recording_id)

Solution: Eliminate the Chapter layer entirely.

OLD MODEL:
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Stories    │────▶│   Chapters   │────▶│    Books     │
└──────────────┘     └──────────────┘     └──────────────┘
      │                    │
      │  content duplicated here
      ▼                    ▼
   editing              editing
   required             required

NEW MODEL:
┌──────────────┐                          ┌──────────────┐
│   Stories    │─────────────────────────▶│    Books     │
└──────────────┘                          └──────────────┘
      │                                         │
      ▼                                         ▼
   single source                        story_ids[] array
   of truth                             (ordered list)

Implementation Details

1. Stories are the unit of content - All editing happens on stories
2. Books reference stories by ID - story_ids UUID[] array maintains order
3. Section breaks are metadata - section_breaks JSONB stores where to add “Part 1”, “Part 2” etc.
4. Story belongs to ONE book - If needed in multiple books, duplicate the story

Current State Assessment

Navigation Structure Issues

Database Architecture (Validated 2025-01-29)

Target State Vision

Simplified Navigation (Target)

MAIN
├── Dashboard                    [Home - personalized, focused]

CREATE (Primary actions)
├── Create Story                 [Modal: Write, Voice, AI, Import]
├── Story Projects               [Preserves storyteller_name, relationship]

LIBRARY
├── Stories                     [With "Add to Book" CTA]
├── Books                       [Ordered story collections]
├── Media                       [Gallery]

FAMILY
├── Family                      [Members & sharing]

ACCOUNT (Footer)
├── Settings                    [Consolidated]
├── Help

IMPORTANT: We use “Story Projects” not “Collections” to preserve the semantics of storyteller_name and relationship fields in the campaigns table.

Simplified User Journey (Target)

┌─────────────────────────────────────────┐
│         "Create Story" Button           │
│    (One entry point, always visible)    │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│         Choose Your Method              │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌──────┐      │
│  │Write│ │Voice│ │ AI  │ │Import│      │
│  └─────┘ └─────┘ └─────┘ └──────┘      │
│           ▲                             │
│           │ Recommended (primary CTA)   │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│         Story Created/Enhanced          │
│   Voice/Conversation attached as        │
│   artifacts (source_recording_ids[],    │
│   source_conversation_ids[])            │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│      "Add to Book?" (Always asked)      │
│   [Add to Current Book] [Save for Later]│
└─────────────────────────────────────────┘

Implementation Phases

Overview

Dependencies

Phase 1 ──────► Phase 2 ──────► Phase 3 ──────► Phase 4
(No deps)      (Needs P1)      (Needs P2)      (Needs P3)

Phase 1: Foundation & Navigation

Goal: Quick wins that improve UX without changing data model.

1.1 Replace Browser Dialogs with Radix Modals

Use existing Radix-based dialog pattern from @/components/ui/dialog:

import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
} from '@/components/ui/dialog'

IMPORTANT: Use @/components/ui/dialog (Radix-based), NOT @headlessui/react.

1.2 Enable Breadcrumbs

Render the existing Breadcrumbs component (already implemented at components/navigation/Breadcrumbs.tsx).

1.3 Update Navigation Labels

• Keep “Story Projects” (NOT “Collections”)
• Remove “Book Designer” from main nav
• Remove “KDP Manager” and “Export Center” from main nav

Phase 1 Testing Checkpoint

• All save/delete confirmations use Radix Dialog
• Breadcrumbs appear on nested pages
• All pages have title + description
• “Story Projects” label appears in nav
• No JavaScript console errors

Phase 2: Unified Content Creation

Goal: Consolidate 4 content creation paths into 1 unified experience.

2.1 Create Story Creation Modal

Single entry point with 4 options:

1. Voice (Recommended for seniors)
2. AI Conversation (Elena)
3. Write
4. Import

2.2 Add Global “Create Story” Button

Always visible at top of sidebar.

2.3 Simplify Sidebar Navigation

Reduce to ~7 items maximum.

Phase 3: Story-Centric Data Model

Goal: Implement Story = Chapter model, eliminate book_chapters complexity.

3.1 Add source_recording_ids to Stories

ALTER TABLE stories ADD COLUMN IF NOT EXISTS source_recording_ids UUID[];
CREATE INDEX IF NOT EXISTS idx_stories_source_recording_ids
  ON stories USING GIN(source_recording_ids);

3.2 Add section_breaks to Books

ALTER TABLE books ADD COLUMN IF NOT EXISTS section_breaks JSONB DEFAULT '{}';

3.3 Update Query Patterns

After:

const { data: book } = await supabase
  .from('books')
  .select('*')
  .eq('id', bookId)
  .single()
 
if (book?.story_ids?.length) {
  const { data: stories } = await supabase
    .from('stories')
    .select('*')
    .in('id', book.story_ids)
 
  // Reorder to match story_ids order
  const orderedStories = book.story_ids
    .map(id => stories?.find(s => s.id === id))
    .filter(Boolean)
}

3.4 Deprecate book_chapters Table

ALTER TABLE IF EXISTS book_chapters RENAME TO _deprecated_book_chapters;

Phase 4: Editor Progressive Disclosure

Goal: Simplify TipTap editor for seniors while preserving power.

Progressive Disclosure Strategy

Level 1 (Default): Bold, Italic, Underline, Headings, Lists, Images, Undo/Redo

Level 2 (Show More): Blockquotes, Links, Text alignment, Colors

Level 3 (Advanced): Tables, Columns, Callouts, Templates, AI assistance

Family Collaboration Model

Access Levels

Amendment Log

Related Documents

• Quick Reference - One-page decision guide
• Database Schema v1.1 - Complete schema documentation
• Implementation Gap Analysis - Current vs target gaps
• Competitor Analysis - Industry research