Complete Diagram Architecture
Navigation: README | Diagram Architecture | How It Works | Database Schema | Challenge Requirements | Deployment
This document visualizes the architecture and data flows of KidStory, built for the Google for Startups AI Agents Challenge. The application uses an Agentic Workflow to orchestrate specialized Gemini models into a cohesive multilingual, multimodal user experience.
Challenge Development
KidStory was started as a basic prototype in March 2026 and substantially upgraded during the Google for Startups AI Agents Challenge (April 25 – June 12, 2026) — migrating to Google ADK v1.0, growing from 2 raw API calls to 9 specialized agents, adding simulation testing, observability, 21 languages, RAG agents, and a full credit system.
For the complete development journey with commit links and what was built during the challenge period, see Challenge Requirements.
Complete Diagram Architecture
Click here to view the full diagram in a new tab.
1. High-Level System Architecture
2. Story Generation Pipeline (3-Step Sequential)
The story is generated in three clean sequential steps: text first, then images, then audio — no interleaved mixing.
3. Magic Quiz — Multi-Type Multilingual Flow
The quiz generates different question types per round and always uses the story's stored language field.
4. Magic Quiz State Machine
5. Language Flow — End to End
6. Deployment Architecture
Key Infrastructure Components
| Component | Purpose | Configuration |
|---|---|---|
| Cloud Run | Hosts Next.js app | Min instances: 1, Region: us-central1 |
| Cloud Storage | Stores media files | CORS enabled, public read |
| Firestore | User data & stories | Native mode, language field on stories |
| Vertex AI | AI model access | Gemini 2.5 Pro, Gemini 2.5 Flash Image, TTS |
| Firebase Auth | User authentication | Google OAuth |
| Cloud Build | CI/CD pipeline | Automatic container builds |
| Artifact Registry | Container storage | Docker images |
7. Credit System Flow
Credit Tiers
| Plan | Monthly Credits | Story Cost | Quiz Cost | Price |
|---|---|---|---|---|
| Free | 30 | 5 credits | 1 credit | $0 |
| Pro | 150 | 5 credits | 1 credit | $4.99/month |
Credits reset automatically on the 1st of each month. Deduction happens server-side via lib/credits/serverCredits.ts using Firebase Admin SDK — only after the safety check passes.
Environment Variables
Runtime (cloudbuild.yaml / Cloud Run):
| Variable | Description | Default |
|---|---|---|
GOOGLE_CLOUD_PROJECT | GCP project ID | storybook-for-kids |
GOOGLE_CLOUD_REGION | Vertex AI region | us-central1 |
GCS_BUCKET_NAME | Storage bucket | storybook-for-kids-media |
GEMINI_STORY_MODEL | Story text generation model | gemini-2.5-pro |
GEMINI_IMAGE_MODEL | Illustration generation model | gemini-2.5-flash-image |
GEMINI_TTS_MODEL | Text-to-speech model | gemini-2.5-flash-preview-tts |
GEMINI_QUIZ_MODEL | Quiz generation model | gemini-2.5-pro |
8. Feedback System Flow
Firestore path: feedback/{feedbackId}
| Field | Type | Description |
|---|---|---|
userId | String | Firebase Auth UID |
rating | Number | 1-5 |
message | String | Optional text |
language | String | "en" or "tet" |
createdAt | String | ISO timestamp |
Security: authenticated users can create only. Admin reads via Firebase Console.
9. Multi-Agent Collaboration Graph
This diagram shows how KidStory's 9 specialized agents collaborate — not as a linear pipeline, but as a network where agents hand off results, run in parallel, and feed each other's context.
Agent Collaboration Highlights
| Collaboration | Type | Detail |
|---|---|---|
| StoryOrchestrator → SafetyGuardian | Sequential gate | Story only proceeds if approved; 0 credits charged on block |
| StoryOrchestrator → StoryWriter | Sequential handoff | Prompt + character refs → structured title + pages + imagePrompts |
| StoryOrchestrator → Illustrator + Narrator | Mixed | Narrator: all pages parallel. Illustrator: sequential with 32s start-to-start gap (2 RPM quota). Pages assembled as results arrive. |
| QuizMaster → 5 questions | Parallel | All 5 questions generated concurrently via Promise.all; pre-generates encouragement/correction text |
| Firestore → LearningAdvisor | RAG (private data) | Last 10 quiz scores retrieved at query time → grounded difficulty + theme recommendation |
| Firestore → ParentInsights | RAG (private data) | Full story + quiz history retrieved → grounded child progress report |
| Firestore → StoryAdaptation | RAG (private data) | Last 3 quiz records retrieved → adapted prompt + vocabulary level + page count; closes learning loop |
| StoryAdaptation → StoryWriter | Adaptive loop | Adapted prompt passed to /create → StoryWriter generates story at the calibrated level |
10. Safety Check — Detailed Flow
The safety popup shows:
- Category pills (violence, adult content, drugs, etc.) from client-side detection
- AI explanation from Gemini's
flag_unsafe_contenttool call reason field - "Edit My Idea" and "Start Over" buttons