🏗️ Kahani Magic Overview

Architecture, lifecycle, and data flow
Last Updated: January 21, 2026

---

Book Lifecycle

flowchart LR
    CREATE["1. CREATE"] --> MANAGE["2. MANAGE"]
    MANAGE --> EXPORT["3. EXPORT"]
    EXPORT --> PUBLISH["4. PUBLISH"]

---

1. CREATE Phase

Input Methods

| Method | Status | Notes | |--------|--------|-------| | Topic Prompt | ✅ | Free-form text | | PDF Upload | ✅ | Context extracted | | Image Upload | ✅ | Visual context | | Story Length | ✅ | 3-50 pages |

Creation Modes

| Mode | Description | Status | |------|-------------|--------| | Classic Storybook | Image + Text per page | ✅ | | Cinematic Video | Timeline-based video | 🔶 Partial |

Profile System (3 Tabs)

| Tab | Features | |-----|----------| | Name | Hero name, Profile name, Context | | Voice | Record/Upload, AI matching | | Photo | Upload, Appearance extraction |

Presets

| Category | Options | |----------|---------| | Ages | 6 (Young → Family) | | Styles | 10 (Mythology → Romance) | | Traditions | 6 (World Cinema → Magical Realism) | | Images | 10 (3D → Fantasy Art) | | Voices | 11 (Child → Motivational) | | Length | 3 (Concise → Extensive) |

---

2. MANAGE Phase (Editor)

UI Layout

┌───────────────────────────────────────────────┐
│  TopControls (Back, Language, Play, BGM, Menu)│
├─────────┬─────────────────────────────────────┤
│         │                                     │
│  Style  │        BookReader                   │
│  Tool-  │   (Image + Text + Animations)       │
│  bar    │                                     │
│         ├─────────────────────────────────────┤
│         │     Thumbnail Navigation            │
└─────────┴─────────────────────────────────────┘

Top Controls

| Control | Description | |---------|-------------| | ← Back | Return to library | | Language | Switch language | | ▶ Play | Auto-play toggle | | 🎵 BGM | Toggle music | | ⚙ Menu | Actions menu |

Style Toolbar

| Section | Options | |---------|---------| | Animation Presets | 8 presets | | Animation Mode | Highlight/Kinetic/Caption | | Text Effects | Glow, Shadow, Outline, Neon, 3D | | Highlight Colors | 18+ colors | | Audio Controls | Narration, BGM, SFX sliders |

---

3. EXPORT Phase

| Format | Method | Status | |--------|--------|--------| | MP4 Video | Remotion SSR | ✅ | | WebM Recording | Browser MediaRecorder | ✅ | | PDF | Not implemented | ❌ | | Image Sequence | Not implemented | ❌ |

---

4. PUBLISH Phase

| Feature | Status | |---------|--------| | Library Save | ✅ Local + Cloud | | Share Link | ✅ Public URL | | Embed Code | ❌ TODO | | Social Sharing | ❌ TODO |

---

Data Flow Diagram

flowchart TD
    subgraph Create
        A[User Input] --> B[PresetSelector]
        B --> C[ProfileModal]
        C --> D[/generate-story/]
    end
    
    subgraph Generate["Per-Page Generation"]
        D --> E[Story JSON]
        E --> F[/generate-image/]
        E --> G[/generate-audio/]
        G --> H[/analyze-phrases/]
        G --> I[/generate-kinetic/]
        G --> J[/generate-audio-cues/]
    end
    
    subgraph Display
        F --> K[BookReader]
        G --> K
        H --> K
        I --> K
        J --> K
    end
    
    subgraph Storage
        K --> L{Save?}
        L -->|Yes| M[Firebase]
        L -->|Yes| N[Hostinger CDN]
    end

---

File Structure

src/app/studio/kahani-magic/
├── page.tsx              # 28KB - Main entry, state management
├── layout.tsx            # Layout wrapper
│
├── components/           # 30 components
│   ├── BookReader/       # Core reader
│   │   ├── hooks/        # 15 hooks (audio, navigation, etc.)
│   │   ├── layers/       # 3 render layers
│   │   └── components/   # 4 sub-components
│   ├── StyleToolbar.tsx  # 20KB - Left panel
│   ├── TopControls.tsx   # 25KB - Top bar
│   ├── PresetSelector.tsx # 22KB - Creation presets
│   └── ProfileModal.tsx  # 23KB - Profile creation
│
├── services/             # 19 services
│   ├── bgmService.ts     # Background music
│   ├── sfxService.ts     # Sound effects
│   ├── storageService.ts # Persistence
│   └── ...
│
├── presets/              # 9 preset configs
│   ├── styles.ts         # Story styles
│   ├── voiceStyles.ts    # Voice presets
│   ├── imageStyles.ts    # Image styles
│   └── ...
│
└── utils/                # Utilities

src/app/api/kahani-magic/ # 18 API routes

---

State Management

Main State (page.tsx)

// Core state
const [story, setStory] = useState<Story | null>(null);
const [currentPage, setCurrentPage] = useState(0);
const [appState, setAppState] = useState<AppState>(AppState.CREATE);

// Generation config
const [presetSelection, setPresetSelection] = useState<PresetSelection>();
const [selectedProfile, setSelectedProfile] = useState<StoryProfile>();

Context (BookReaderContext)

interface BookReaderContextValue {
  story: Story;
  currentPage: number;
  setCurrentPage: (page: number) => void;
  isPlaying: boolean;
  // ... 20+ more fields
}

---

Key Hooks

| Hook | Purpose | |------|---------| | useAudioPlayer | 900+ lines - Narration playback | | useTranslation | 500+ lines - Multi-language | | useGeneration | Asset generation | | useEditMode | Text editing | | useAudioCues | BGM/SFX integration | | usePersistence | Save/load | | useExport | Video/recording export |

---

External Services

| Service | Purpose | |---------|---------| | Google Gemini | Story gen, TTS, image prompt enhancement | | Imagen 3 | Image generation | | ElevenLabs | TTS, sound effects | | Deepgram | Audio transcription | | Veo 2 | Video generation | | Firebase | Story storage | | Hostinger | Media CDN | | Remotion | Video rendering |

---

See linked docs for detailed specifications