📖 Kahani Magic - Developer Documentation

Complete technical reference for Kahani Magic studio
Last Updated: January 21, 2026

---

📌 Quick Navigation

| Document | Description | |----------|-------------| | OVERVIEW.md | Architecture, lifecycle, data flow | | ASSETS.md | 9 assets with full lifecycle specs | | APIS.md | 18 API routes documentation | | AUDIO-SYSTEM.md | Complete audio architecture & roadmap | | COMPONENTS.md | 30+ components & hooks | | SERVICES.md | 19 services reference | | TYPES.md | TypeScript interfaces | | ISSUES.md | Known issues & priorities | | PRESETS.md | All configurable presets |

---

🏗️ Architecture Overview

flowchart TB
    subgraph Page["page.tsx (Main Entry)"]
        InputForm --> PresetSelector --> ProfileModal
        BookReader --> Services
    end
    
    subgraph Services["19 Services"]
        bgmService --> sfxService
        storageService --> recordingService
    end
    
    subgraph APIs["18 API Routes"]
        generate-story --> generate-image --> generate-audio
        analyze-phrases --> generate-kinetic
    end
    
    subgraph Storage["Storage Layer"]
        Firebase --> Supabase --> Hostinger
    end
    
    Page --> APIs --> Storage

---

📦 Asset Summary

| Asset | Type | API | Status | |-------|------|-----|--------| | IMG | Image | /generate-image | ✅ Gen ⚠️ No Edit | | TXT | Text | /generate-story | ✅ Full | | AUD | Audio | /generate-audio | 🔴 No Timestamps | | HIGH | Highlights | /align-text | 🔴 Heuristic | | CAP | Captions | /analyze-phrases | ⚠️ Lang Missing | | KIN | Kinetic | /generate-kinetic | ⚠️ Array Sync | | BGM | Music | bgmService.ts | ✅ Working | | SFX | Effects | /generate-sfx | ✅ Working | | VID | Video | /generate-segment | ✅ Working |

---

🔗 Related Docs

| Doc | Path | |-----|------| | Platform Architecture | ../ARCHITECTURE.md | | Data Flows | ../DATA_FLOWS.md | | API Reference | ../API_REFERENCE.md | | Kahani Config | ../KAHANI_MAGIC_CONFIG.md |

---

📁 Code Locations

src/app/studio/kahani-magic/
├── page.tsx              # Main entry (28KB)
├── layout.tsx            # Layout wrapper
├── components/           # 30 components
│   ├── BookReader/       # Reader system
│   │   ├── hooks/        # 15 hooks
│   │   └── layers/       # Render layers
│   ├── StyleToolbar.tsx  # Left panel
│   └── TopControls.tsx   # Top bar
├── services/             # 19 services
├── presets/              # 9 preset configs
└── utils/                # Utilities

src/app/api/kahani-magic/
├── generate-story/       # Story generation
├── generate-image/       # Image generation
├── generate-audio/       # TTS generation
├── analyze-phrases/      # Caption analysis
├── generate-kinetic/     # Animation generation
└── ... (18 total)

---

See individual docs for detailed specifications