Architecture Quick Reference v1.1

Last Updated: 2025-11-30

The Golden Rule

Story = Chapter

A story IS a chapter. When added to a book, a story becomes a chapter. No intermediate layer.

Voice/Conversation → Story → Book
        ↑              ↑       ↑
    artifacts     the unit   ordered
    (preserved)   of content collection

Before Making ANY Changes, Ask:

1. Does this follow the Story = Chapter model?
2. Does this use direct relationships (user_id on content)?
3. Is this documented in the v1.1 roadmap?
4. Does this use Radix Dialog (NOT Headless UI)?

If NO to any, stop and update the roadmap first.

Target User Journey

CREATE → REVIEW → ADD TO BOOK → PUBLISH

That’s it. Every feature should support this flow.

Navigation (Current vs Target State)

Current State: 7 sections with 20+ navigation items (needs simplification)

Target State:

[Create Story Button]  ← Always visible at top

Dashboard
Stories
Books
Story Projects           (NOT "Collections" - preserves storyteller semantics)
Media
Family
---
Settings
Help

MAX 10 items. If you need to add something, remove something else.

Note: Navigation simplification is part of Phase 1 (In Progress). Current implementation has more sections and items than the target state.

Database Relationships

User → Story (DIRECT via user_id)
User → Book (DIRECT via user_id)
Story → Book (via books.story_ids[] array)

NOT: User → Campaign → Story (INDIRECT) NOT: Story → Chapter → Book (ELIMINATED)

Current Schema Status

Key Files to Know

Note: StoryConversionModal builds its own modal structure. Consider migrating to use Dialog component from @/components/ui/dialog for consistency.

Do’s and Don’ts

DO

• Use Radix-based Dialog from @/components/ui/dialog
• Add stories directly to books.story_ids[]
• Preserve voice/conversation as artifacts on stories
• Keep navigation under 10 items
• Use “Story Projects” (not “Collections”)
• Test on mobile

DON’T

• Use Headless UI (@headlessui/react) - No longer in dependencies
• Create book_chapters records - Table has been dropped
• Use browser alert() or confirm()
• Add new navigation sections
• Skip the roadmap phases
• Deploy without testing checkpoints

Component Patterns

Dialog (Correct)

import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
} from '@/components/ui/dialog'
 
<Dialog open={open} onOpenChange={setOpen}>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
    </DialogHeader>
    {/* content */}
  </DialogContent>
</Dialog>

Dialog (WRONG - Don’t Use)

// DON'T USE HEADLESS UI
import { Dialog } from '@headlessui/react'

Adding a Story to a Book

// Get current book
const { data: book } = await supabase
  .from('books')
  .select('story_ids')
  .eq('id', bookId)
  .single()
 
// Add story to end
const newStoryIds = [...(book?.story_ids || []), storyId]
 
// Update book
await supabase
  .from('books')
  .update({ story_ids: newStoryIds })
  .eq('id', bookId)

Current Phase Status

Competitive Advantages

1. Voice-First - Record naturally, we transcribe
2. AI Conversation (Elena) - Guided story extraction
3. Voice Preservation - Audio in digital books
4. Family Collaboration - Multiple contributors
5. Progressive Editor - Simple → Advanced

Common Development Commands

# Start all development servers
npm run dev
 
# Start specific apps
npm run dev:app          # Web app (main application)
npm run dev:docs         # Documentation app
npm run dev:marketing    # Marketing site
npm run dev:admin        # Admin dashboard
npm run dev:tools        # Developer tools
 
# Build for production
npm run build
 
# Run tests
npm run test             # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # With coverage report
 
# Linting
npm run lint
 
# Deployment checks
npm run deploy:check

Emergency Contacts

• Full roadmap: v1.1 UX Roadmap
• Competitor analysis: Competitor Analysis
• Database schema: Database Schema v1.1
• Gap analysis: Implementation Gap Analysis