KidStory Documentation Site

Full project documentation for KidStory, built with VitePress and deployed at docs.kidstory.app.

---

Pages

Home — /

Documentation homepage with quick links to all sections, feature highlights, and links to the live app and GitHub.

---

Getting Started — /getting-started

Root README with the full project overview, development journey for judges, problem statement, solution, and quick-start guide. Synced from README.md.

---

App Overview — /app/

Main app README: key features, tech stack, complete diagram architecture, API routes, hooks, and component overview. Synced from storybook-for-kids-app/README.md.

---

How It Works — /app/how-this-app-work

Step-by-step explanation of the story creation pipeline, quiz system, personalized learning, observability, and Android app. Synced from storybook-for-kids-app/document/how-this-app-work.md.

---

Architecture & Diagrams — /app/all_diagram

Complete workflow diagram, sequence diagrams (story generation, quiz, adaptive learning), state machines, and data flows. Mermaid diagrams are clickable to open full-screen. Synced from storybook-for-kids-app/document/all_diagram.md.

---

AI Agents — /agents/

Documentation for all 9 ADK agents: SafetyGuardian, StoryWriter, Illustrator, Narrator, QuizMaster, QuizFeedback, LearningAdvisor, ParentInsights, StoryAdaptation. Each agent has its own page with tools, flow, observability spans, and simulation test cases.

---

Features — /features/

Individual documentation pages for every feature:

Feature	Route
Credit System	/features/credit-system
Referral System	/features/referral-system
Story Map	/features/story-map
Character Collection	/features/character-collection
Profile & Badges	/features/profile-and-badges
Reading Streak	/features/reading-streak
Page Flip Animation	/features/page-flip-animation
Cover Generation	/features/cover-generation
Recommendation Audio	/features/recommendation-audio
Observability Dashboard	/features/observability-dashboard

---

Admin Panel — /admin/

Documentation for the local-only admin dashboard: all 8 pages (Dashboard, Users, User Detail, Stories, Feedback, Analytics, Growth, Donors) with screenshots. Synced from storybook-for-kids-adm/README.md.

---

Challenge Requirements — /app/Challenge

How KidStory meets every Google for Startups AI Agents Challenge requirement (Track 2: Optimize). Includes development timeline, mandatory technologies checklist, optimization work, and judging criteria alignment. Synced from storybook-for-kids-app/document/Challenge.md.

---

Database Schema — /app/database

Firestore data models, collection structure, supported languages table, and Cloud Storage layout. Synced from storybook-for-kids-app/document/database.md.

---

Cost Tracking — /app/cost-tracking

Dev-only token usage logging, cost per story (~$0.14), cost per quiz (~$0.014), pricing reference for Gemini 2.5 on Vertex AI, and cost report script. Synced from storybook-for-kids-app/document/cost-tracking.md.

---

Deployment Guide — /app/deployment

Step-by-step Google Cloud Run deployment, IAM setup, environment variables, and troubleshooting. Synced from storybook-for-kids-app/DEPLOYMENT.md.

---

Landing Page — /landing/

Documentation for the marketing landing page at kidstory.app. Synced from storybook-for-kids-landing/README.md.

---

How Docs Are Generated

Do not edit files inside docs/ directly — most content is auto-synced by sync-docs.js.

Source files                           →  sync-docs.js  →  docs/ (VitePress)
──────────────────────────────────────────────────────────────────────────────
README.md                              →  getting-started.md
storybook-for-kids-app/README.md       →  app/index.md
storybook-for-kids-app/document/*.md   →  app/*.md
storybook-for-kids-app/document/       →  agents/*.md
  agent-doc/*.md                           features/*.md
storybook-for-kids-adm/README.md       →  admin/index.md   ← NEW
storybook-for-kids-landing/README.md   →  landing/index.md

Files that can be edited directly:

• docs/index.md — homepage (not synced)
• docs/.vitepress/config.mjs — sidebar/nav config
• docs/.vitepress/theme/style.css — styles
• docs/.vitepress/theme/MermaidZoom.vue — click-to-expand Mermaid diagrams

---

Development

# Install dependencies
npm install

# Sync all docs from source repos
npm run sync

# Start local dev server (http://localhost:5173)
npm run docs:dev

# Build for production
npm run docs:build

# Preview production build
npm run docs:preview

Always run npm run sync before npm run docs:dev to get the latest content from all source repos.

---

Project Structure

storybook-for-kids-docs/
├── docs/
│   ├── index.md                    # Homepage (edit directly)
│   ├── getting-started.md          # ← synced from README.md
│   ├── app/                        # ← synced from storybook-for-kids-app/
│   │   ├── index.md
│   │   ├── how-this-app-work.md
│   │   ├── all_diagram.md
│   │   ├── database.md
│   │   ├── Challenge.md
│   │   ├── cost-tracking.md
│   │   └── deployment.md
│   ├── agents/                     # ← synced from agent-doc/
│   │   ├── index.md
│   │   ├── safety-guardian.md
│   │   ├── story-writer.md
│   │   ├── illustrator.md
│   │   ├── narrator.md
│   │   ├── quiz-master.md
│   │   ├── quiz-feedback.md
│   │   ├── learning-advisor.md
│   │   ├── parent-insights.md
│   │   └── story-adaptation.md
│   ├── features/                   # ← synced from features/
│   │   ├── credit-system.md
│   │   ├── referral-system.md
│   │   ├── story-map.md
│   │   ├── character-collection.md
│   │   ├── profile-and-badges.md
│   │   ├── reading-streak.md
│   │   ├── page-flip-animation.md
│   │   ├── cover-generation.md
│   │   ├── recommendation-audio.md
│   │   └── observability-dashboard.md
│   ├── admin/                      # ← synced from storybook-for-kids-adm/
│   │   └── index.md
│   ├── landing/                    # ← synced from storybook-for-kids-landing/
│   │   └── index.md
│   ├── public/                     # Static assets
│   │   ├── logo.png
│   │   └── documentation_mascot.png
│   └── .vitepress/
│       ├── config.mjs              # Sidebar, nav, Mermaid config (edit directly)
│       └── theme/
│           ├── index.js            # Theme entry — injects MermaidZoom globally
│           ├── style.css           # Global styles + Mermaid zoom CSS
│           └── MermaidZoom.vue     # Click-to-expand Mermaid diagrams
├── sync-docs.js                    # Sync script — rewrites links for VitePress
└── package.json

---

Theme Features

• Light/Dark mode — VitePress default theme with custom Fredoka/Nunito fonts
• Mermaid diagrams — all diagrams scale to page width; click any diagram to open full-screen popup (MermaidZoom.vue)
• Custom CSS — style.css includes Mermaid scaling, overlay styles, and font overrides

---

Related Projects

• Main App: storybook-for-kids-app — ai.kidstory.app
• Landing Page: storybook-for-kids-landing — kidstory.app
• Admin Panel: storybook-for-kids-adm — local only
• Documentation Site: This project — docs.kidstory.app