System Architecture & Diagrams

Navigation: README | Architecture & Diagrams | How It Works | Database Schema | Hackathon Requirements | Deployment

This document visualizes the architecture and data flows of KidStory, built for the Gemini Live Agent Challenge. The application uses an Agentic Workflow to orchestrate specialized Gemini models into a cohesive user experience, with a focus on interleaved output for multimodal storytelling.

Hackathon Development

March 5, 2026: Project inception - Built from scratch for Gemini Live Agent Challenge, continue development for Core architecture, Gemini 2.5 Flash Image integration, and develop Interleaved output implementation for stories, and then Voice integration & quiz system after that Polish, testing, and hackathon submission

For hackathon submission details, see meet_hackathon_requirement.md.

Complete System Architecture

Click here to view the full diagram in a new tab.

---

1. High-Level System Architecture

---

2. Story Generation Pipeline (Interleaved Output)

This sequence diagram illustrates the interleaved generation pattern for story creation, where text and images are generated together in a single stream.

---

3. Magic Quiz: Optimized Text-Only Flow

This diagram shows the optimized model orchestration for quiz generation, demonstrating intelligent model selection for different tasks.

---

4. Magic Quiz State Machine

---

5. Data Flow Overview (Interleaved Focus)

---

6. Deployment Architecture

This diagram shows the complete deployment infrastructure on Google Cloud Platform.

Deployment Flow

1. Setup Phase (One-time):

   # Configure permissions
   ./fix_permissions.sh

   • Creates service accounts
   • Grants IAM roles
   • Enables required APIs

2. Build Phase:

   # Deploy application
   ./deploy.sh

   • Builds Next.js app with .env.production
   • Creates container image
   • Pushes to Artifact Registry

3. Deploy Phase:

   • Cloud Run pulls container image
   • Sets runtime environment variables
   • Deploys with min-instances=1 (always warm)

4. Post-Deploy:

   # Update NEXTAUTH_URL automatically
   ./update_url.sh

   • Gets service URL
   • Updates environment variable

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
Vertex AI	AI model access	Gemini 2.5 models
Firebase Auth	User authentication	Google OAuth
Cloud Build	CI/CD pipeline	Automatic container builds
Artifact Registry	Container storage	Docker images

Security & Permissions

Service Accounts:

• Cloud Build SA: Build and deploy permissions
• Compute Engine SA: Runtime access to GCP services

IAM Roles:

• roles/run.admin - Deploy Cloud Run services
• roles/aiplatform.user - Access Vertex AI models
• roles/storage.objectAdmin - Read/write Cloud Storage
• roles/datastore.user - Access Firestore
• roles/iam.serviceAccountUser - Use service accounts

Environment Variables

Build-time (.env.production):

• NEXT_PUBLIC_FIREBASE_* - Firebase client config

Runtime (deploy.sh):

• GOOGLE_CLOUD_PROJECT - GCP project ID
• GCS_BUCKET_NAME - Storage bucket
• FIREBASE_CLIENT_EMAIL - Service account
• GEMINI_*_MODEL - AI model names
• NEXTAUTH_SECRET - Auth secret
• NEXTAUTH_URL - Service URL (auto-updated)