LearnForge

Forge Your Path. Learn Your Way.

Comment

LearnForge: AI-Powered Personalized Learning Platform

What is LearnForge?

LearnForge is an intelligent, AI-driven learning platform that transforms how people learn by providing deeply personalized, adaptive educational experiences. Built entirely on Google Cloud infrastructure and powered by Google's Agent Development Kit (ADK) with Gemini 2.5 Flash, LearnForge guides learners from vague interests to mastery through two sophisticated AI agents: Polaris and Lumina.

LearnForge doesn't just deliver content, it creates a complete learning journey. The system understands each learner's goals, experience level, and preferred learning style, then dynamically generates structured learning missions, delivers personalized content, and adapts in real-time to ensure true comprehension and mastery.

Agent Architecture

LearnForge uses two sophisticated AI agents that work together to create a complete learning experience:

Polaris: The Pathfinder

Polaris is a research-augmented mentor agent that transforms vague learning interests into precise, actionable learning goals. It serves as the entry point to the LearnForge ecosystem, engaging users in intelligent, context-aware conversations to define their learning objectives.

Architecture Hierarchy

Orchestrator Agent
    ├── Pathfinder Agent (Polaris)
    │   └── Search Agent (Google Search Tool)
    └── Mission Curator Agent

Core Components

Agent Functionality
Orchestrator Agent Manages agent transitions and coordinates mission creation flow
Pathfinder Agent (Polaris) Transforms vague learning interests into precise, actionable learning goals using Google Search for research-backed questions
Mission Curator Agent Converts Pathfinder's collected data into structured mission schema with checkpoints and learning goals

Session Management

  • Storage: InMemorySessionService for ephemeral session storage
  • Scope: Sessions scoped to WebSocket connection lifecycle
  • Use Case: Perfect for short-duration goal clarification sessions

Lumina: The Learning Companion

Lumina is the comprehensive teaching agent that guides learners through their personalized missions. It orchestrates a multi-phase learning experience across sequential checkpoints, delivering adaptive content, interactive teaching, and progress tracking.

Architecture Hierarchy

Lumina Orchestrator
    ├── Greeter Agent
    ├── Flow Briefer Agent
    │   └── Update Checkpoint Goal Tool
    ├── Sensei Agent (Teaching Core)
    │   ├── Content Composer Agent
    │   │   ├── Content Searcher Agent (Google Search)
    │   │   ├── Video Selector Agent (YouTube API v3)
    │   │   └── Content Formatter Agent
    │   └── Mark Complete Tool
    ├── Help Desk Agent (Google Search)
    └── Wrapper Agent

Core Components

Agent Functionality
Lumina Orchestrator Coordinates learning journey through sequential checkpoints
Greeter Agent Provides initial welcome and mission introduction
Flow Briefer Agent Briefs user on upcoming checkpoint and confirms learning objectives
Sensei Agent Interactive teaching agent that presents content and evaluates understanding
Content Composer Agent Orchestrates content creation pipeline
Content Searcher Agent Uses Google Search to find educational text content
Video Selector Agent Uses YouTube Data API v3 to find and select relevant educational videos
Content Formatter Agent Formats and personalizes content based on user preferences
Help Desk Agent Handles off-topic questions during missions using Google Search
Wrapper Agent Provides final mission wrap-up and celebration

Session Management

  • Storage: DatabaseSessionService with Cloud SQL (PostgreSQL)
  • Connection: Cloud SQL Connector for secure database access
  • Pooling: 10 base connections, 5 overflow, 60s timeout
  • Benefits: Persistent state enables session resume and progress tracking across devices

System Architecture

LearnForge is built as a modern, cloud-native application leveraging Google Cloud Platform's comprehensive ecosystem for scalability, reliability, and observability.

Infrastructure Overview

┌──────────────────────────────────────────────────────────────────┐
│                    FRONTEND (Cloud Run)                           │
│           React + Firebase Auth + WebSocket Client                │
└──────────────────────────────────────────────────────────────────┘
                              │
                              │ WebSocket + REST API
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│         BACKEND (Cloud Run)                                       │
│      FastAPI + Google ADK + Gemini 2.5 Flash                     │
│      ┌────────────────────────────────────────────┐              │
│      │  Polaris (Mission Commander)               │              │
│      │  - Pathfinder Agent                        │              │
│      │  - Mission Curator Agent                   │              │
│      └────────────────────────────────────────────┘              │
│      ┌────────────────────────────────────────────┐              │
│      │  Lumina (Mission Ally)                     │              │
│      │  - Greeter, Flow Briefer, Sensei          │              │
│      │  - Content Composer (Searcher, Video,     │              │
│      │    Formatter)                             │              │
│      │  - Help Desk, Wrapper                     │              │
│      └────────────────────────────────────────────┘              │
└──────────────────────────────────────────────────────────────────┘
        │                │                │               │
        ▼                ▼                ▼               ▼
  ┌──────────┐   ┌─────────────┐   ┌──────────┐   ┌──────────┐
  │ Firestore│   │  Cloud SQL  │   │ YouTube  │   │  Google  │
  │          │   │ (PostgreSQL)│   │   API    │   │  Search  │
  │          │   │  Connector  │   │    v3    │   │   API    │
  └──────────┘   └─────────────┘   └──────────┘   └──────────┘

Container Images:

  • Both Frontend and Backend images stored in Artifact Registry
  • Automated CI/CD deployment to Cloud Run on git push

Technology Stack

Frontend

  • Framework: React
  • Hosting: Cloud Run
  • Container Registry: Artifact Registry

Backend

  • Framework: FastAPI (Python 3.11)
  • AI Framework: Google Agent Development Kit (ADK)
  • LLM Model: Gemini 2.5 Flash
  • Hosting: Cloud Run
  • Container Registry: Artifact Registry

Authentication & Authorization

  • Provider: Firebase Authentication
  • Method: Google OAuth 2.0
  • Session Management: Secure HTTP-only cookies
  • API Communication: Token-based (Authorization header)

Data Storage

  • Firestore: User profiles, mission definitions, enrollment records
  • Cloud SQL (PostgreSQL): ADK session state for Lumina agent
  • Cloud SQL Connector: Secure, managed database connections

External APIs

  • YouTube Data API v3: Educational video search and curation
  • Google Search API: Research-augmented content discovery

Observability

  • Cloud Logging: Centralized application logs
  • Cloud Trace: Distributed tracing for request flow analysis

DevOps

  • Artifact Registry: Container image storage and versioning
  • Cloud Run: Serverless container hosting (auto-scaling)
  • Secret Manager: Secure credential storage

Data Flow

User Authentication Flow:

User → Frontend → Firebase OAuth → Backend (/api/v1/auth/create-session)
→ Session Cookie → Subsequent Requests (Authorization Header)

Mission Creation Flow (Polaris):

User → WebSocket → Polaris Orchestrator → Pathfinder Agent
→ Google Search (research) → Goal Confirmation → Mission Curator
→ Firestore (mission creation) → User Notification

Learning Flow (Lumina):

User → WebSocket → Lumina Orchestrator → Greeter → Flow Briefer
→ Sensei → Content Composer → [Content Searcher + Video Selector]
→ YouTube API v3 → Content Formatter → Sensei (teaching)
→ Mark Complete → Increment Checkpoint → Repeat or Wrap Up
→ Cloud SQL (session persistence)

Key Achievements & Technical Highlights

1. DatabaseSessionService with Cloud SQL Integration

Challenge: LearnForge's learning sessions can span multiple hours or days or even months, requiring persistent state management that survives connection drops, server restarts, and concurrent access.

Solution: Implemented DatabaseSessionService using Cloud SQL (PostgreSQL) with the Cloud SQL Connector for secure, managed database connections.

Technical Implementation:

  • Connection Management: Cloud SQL Connector with lazy refresh strategy
  • Connection Pooling: 10 base connections, 5 overflow, 60s timeout, 30min recycle
  • State Persistence: All agent state (checkpoint progress, content search results, video selections) persisted to PostgreSQL
  • Benefits:
    • Sessions survive connection interruptions
    • Enables progress tracking across devices
    • Supports concurrent learners with isolation
    • Production-ready scalability

This was a critical architectural decision that distinguishes LearnForge from ephemeral chatbot experiences, learners can pause and resume their missions seamlessly.

2. Building a Robust Multi-Agent System

Challenge: Coordinating 10+ specialized agents across two distinct learning phases (goal clarification and teaching) while maintaining a seamless user experience.

Solution: Implemented hierarchical agent orchestration with strict separation of concerns and silent coordination patterns.

Key Design Patterns:

  • Silent Orchestration: Orchestrators are invisible to users, all transitions are seamless
  • Content Authority Separation: Teaching agents (Sensei) facilitate learning, content creation agents (Content Composer) generate material
  • State-Driven Flow: Checkpoint progression managed through persistent state, not hardcoded logic
  • Error Resilience: Each agent has defined error handling and fallback behaviors
  • Tool Integration: Clean abstraction between agents and external APIs (YouTube, Google Search)

Agent Hierarchy:

  • 2 Top-Level Orchestrators:
    • Mission Commander (Polaris)
    • Mission Ally (Lumina)
  • 10 Specialized Sub-Agents:
    • Pathfinder, Greeter, Flow Briefer, Sensei, Content Composer, Content Searcher, Video Selector, Content Formatter, Help Desk, Wrapper
  • 10+ Tools: Checkpoint management, content storage, video selection, goal updates, completion tracking

The system handles complex multi-turn conversations, maintains context across agent transitions, and adapts to user responses in real-time, all while appearing as a single, coherent learning companion.

3. Learning Google Cloud Ecosystem During Hackathon

Challenge: Building a production-ready, scalable application on Google Cloud Platform with zero prior experience in Cloud Run, Artifact Registry, Cloud SQL, Cloud Logging, and Cloud Trace.

Solution: Deep dive into Google Cloud documentation, best practices, and hands-on experimentation to implement a fully cloud-native architecture.

Technologies Mastered:

  • Cloud Run: Serverless container hosting with auto-scaling, custom domains, and traffic splitting
  • Artifact Registry: Container image storage, versioning, and CI/CD integration
  • Cloud SQL: Managed PostgreSQL with Cloud SQL Connector for secure connections
  • Cloud Logging: Structured logging, log-based metrics, and log aggregation
  • Cloud Trace: Distributed tracing for performance analysis and debugging
  • Secret Manager: Secure credential management and rotation
  • Firebase: Authentication, Firestore database, and session management
  • Cloud SQL Connector: Secure, IAM-based database connections without IP whitelisting

Architecture Decisions:

  • Separate frontend and backend containers for independent scaling
  • Artifact Registry for versioned container images
  • Cloud SQL Connector for production-grade database access
  • Secret Manager for all sensitive configuration
  • Cloud Logging and Trace for full observability

Outcome: Delivered a production-ready application that leverages Google Cloud's best practices for security, scalability, and observability, all learned and implemented during the hackathon timeframe.

Google Cloud Services Utilized

This project showcases comprehensive use of Google Cloud Platform:

Service Purpose
Cloud Run Serverless container hosting for frontend and backend
Artifact Registry Container image storage and versioning
Cloud SQL (PostgreSQL) Managed database for session persistence
Cloud SQL Connector Secure database connection management
Firebase Authentication OAuth Google authentication
Firestore NoSQL database for user and mission data
Cloud Logging Centralized application logging
Cloud Trace Distributed tracing and performance monitoring
Secret Manager Secure credential storage
Agent Development Kit (ADK) Multi-agent orchestration framework
Gemini 2.5 Flash Large language model for agent intelligence
YouTube Data API v3 Educational video search and curation

Impact & Innovation

LearnForge represents a new paradigm in personalized learning:

  • From Static to Dynamic: Learning paths are generated in real-time based on individual goals
  • From Generic to Personalized: Content adapts to learning style, level, and preferences
  • From Passive to Interactive: Multi-turn conversations ensure comprehension before progression
  • From Ephemeral to Persistent: Sessions survive interruptions, enabling long-form learning
  • From Single-Modal to Multi-Modal: Combines text content with curated video resources

Built entirely on Google Cloud, LearnForge demonstrates how modern cloud infrastructure can power sophisticated AI applications that scale seamlessly while maintaining security, observability, and reliability.

Built With

Share this project:

Updates