Kidlytics is a web application that leverages the power of Google Cloud's Vertex AI to generate engaging and personalized stories for children. By answering a series of fun questions, parents and educators can create unique, illustrated stories tailored to a child's interests and learning goals, all orchestrated by the Genkit framework.

• Kidlytics: AI-Powered Story Generator for Kids
  • Table of Contents
  • Technologies Used
  • Getting Started
    • Prerequisites
    • 1. Clone the Repository
    • 2. Install Dependencies
    • 3. Set Up Google Cloud & Firebase
    • 4. Configure Environment Variables
      • 4.1. Angular Application (Root)
      • 4.2. Firebase Functions (/functions)
    • 5. Deploy Firebase Functions
    • 6. Run the Application
  • Firebase Functions
  • Project Structure
  • How It Works
  • Contributing

• Frontend:

  • Angular: A powerful framework for building dynamic single-page applications.
  • Tailwind CSS: A utility-first CSS framework for rapid UI development.
  • Angular Material: A UI component library for Angular.

• Backend & AI:

  • Node.js with Express: For the server-side logic and API endpoints.
  • Google Cloud Vertex AI: The core platform for hosting and running generative AI models (like Gemini for text and Imagen for images).
  • Genkit: An open-source framework from Google for building, deploying, and monitoring AI-powered applications.
  • Firebase Firestore: A NoSQL database for storing the generated stories.
  • Firebase Functions: For serverless backend logic, such as rate limiting.

• Development & Authentication:

  • Angular CLI: For managing the Angular project.
  • TypeScript: For type-safe JavaScript development.
  • Google Cloud SDK (gcloud): For authenticating the local development environment with your Google Cloud project.

Follow these steps to get a local copy of the project up and running on your machine.

• Node.js (v20.x or higher)
• Angular CLI
• Firebase CLI
• A Google Cloud account with an active billing account.
• The Google Cloud SDK (gcloud CLI) installed and configured on your machine.

Before you begin, make sure you are logged into the Firebase CLI:

firebase login

git clone https://github.com/your-username/kidlytics.git
cd kidlytics

Install the necessary npm packages for both the root project and the functions directory in a single step:

npm install && (cd functions && npm install)

This project uses Google Cloud for AI services and Firebase for the database and serverless functions.

1. Create a Google Cloud Project:

   • Go to the Google Cloud Console and create a new project.
   • Make a note of the Project ID.

2. Enable Required APIs:

   • For your new project, you must enable the Vertex AI API.
   • Visit the Vertex AI API Library page and click Enable.

3. Authenticate via gcloud CLI:

   • This is a crucial step that allows Genkit to securely access your Google Cloud resources without needing to manage API keys in your code.
   • Run the following command in your terminal and follow the prompts to log in with your Google account:

     gcloud auth application-default login

   • Set your active project to the one you just created. This ensures all subsequent gcloud and SDK commands target the correct project.

     gcloud config set project YOUR_PROJECT_ID

     (Replace YOUR_PROJECT_ID with the ID from step 1).

4. Set Up Firebase:

   • Go to the Firebase Console and click "Add project".
   • Select your existing Google Cloud Project to link Firebase to it.
   • From your project's dashboard, create a new Web app (the </> icon).
   • You will be provided with a firebaseConfig object. Copy these keys for the next step.
   • Navigate to the Firestore Database section and create a new database. Start in test mode for easy setup (you can configure security rules later).

This project requires two separate .env files: one for the Angular application and one for the Firebase Functions.

The Angular app uses a script to generate its environment files from a .env file in the root of the project.

1. Create a .env file in the root of the project.

2. Add your configuration keys to the .env file. This file should include your Firebase project details and your Google Cloud Project ID.

   # Firebase Configuration
   API_KEY="YOUR_FIREBASE_API_KEY"
   AUTH_DOMAIN="YOUR_FIREBASE_AUTH_DOMAIN"
   PROJECT_ID="YOUR_FIREBASE_PROJECT_ID"
   STORAGE_BUCKET="YOUR_FIREBASE_STORAGE_BUCKET"
   MESSAGING_SENDER_ID="YOUR_FIREBASE_MESSAGING_SENDER_ID"
   APP_ID="YOUR_FIREBASE_APP_ID"
   
   # Google Cloud Configuration
   GCP_PROJECT_ID="YOUR_GCP_PROJECT_ID" # Should be the same as PROJECT_ID
   
   # Application Settings
   STORY_GENERATION_LIMIT=3
   enableStoryGenerationLimit=true
   ADMIN_PASSWORD="your_secret_password"

3. Run the script to generate the environment.ts and environment.development.ts files:

   npm run generate:env

This command will read your .env file and create the necessary configuration for the Angular application.

The functions directory contains serverless functions that require their own environment variables.

1. Navigate to the functions directory.
2. Create a .env file inside the functions directory.
3. Add the application settings to this functions/.env file. You can copy them from the root .env file.

   # Application Settings
   STORY_GENERATION_LIMIT=3
   enableStoryGenerationLimit=true
   ADMIN_PASSWORD="your_secret_password"

Before running the application, you need to build and deploy the Firebase Functions.

# Make sure you are in the functions directory
cd functions
npm run build
firebase deploy --only functions

For a production environment, it is recommended to set the environment variables directly in the Google Cloud console instead of using a .env file.

Now you can start the Angular development server.

# In one terminal, run the Angular dev server
npm start

Open your browser and navigate to http://localhost:4200/.

This project uses two Firebase Functions located in the functions directory:

• rateLimiter: This function tracks the number of stories generated by a user (based on their IP address) to enforce the generation limit.
• validatePasswordAndOverride: This function allows a user with the correct admin password to bypass the rate limit.

These functions are called by the Angular application to control access to the story generation feature.

Here is an overview of the key files and directories in the project:

.
├── src/
│   ├── app/
│   │   ├── components/       # Reusable UI components
│   │   ├── services/         # Services for API calls (generate-story.ts)
│   │   ├── model/            # TypeScript types and interfaces
│   │   └── ...
│   ├── constants/          # Application constants (e.g., questions.ts)
│   ├── genkit/             # Genkit AI flow definitions (storyGenerationFlow.ts)
│   ├── environments/       # Environment configuration files
│   ├── server.ts           # Express server for handling API requests and Genkit flows
│   └── ...
├── functions/              # Firebase Functions for rate limiting
│   ├── index.ts
│   ├── package.json
│   └── .env                # (You need to create this)
├── angular.json            # Angular project configuration
├── package.json            # Project dependencies and scripts
└── ...

1. User Input: The user answers a series of questions within the Angular app.
2. Rate Limiting: Before generating a story, the app calls the rateLimiter Firebase Function to check if the user has reached their limit.
3. API Call: If allowed, the frontend sends the answers to the backend Express server.
4. Genkit Orchestration: The server triggers the storyGenerationFlow.
5. AI Story and Image Generation: This flow calls the Gemini model on Vertex AI to generate the story text and then uses the Imagen model on Vertex AI to create illustrations for each part of the story.
6. Storing the Story: The complete story, including the text and image data, is saved to Firebase Firestore.
7. Displaying the Story: The user is given a link to a page where they can view the newly generated story with its illustrations.

Contributions are welcome! If you have ideas for new features or improvements, please feel free to open an issue or submit a pull request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request