What This Guide Does

This guide uses an incremental build approach to create your student AI chat interface. You'll build the application in five distinct stages, with each stage producing a fully functional system. Test and verify each stage before moving to the next.

Why Build Incrementally

Clear progress markers - Each stage has specific, testable deliverables. You'll know when you're done.

Easier debugging - When something breaks, you know it's related to the current stage. The previous stage worked.

Flexible stopping points - Each stage produces something functional. Stop at Stage 2 if you just need basic chat with persistence. Continue to Stage 5 for the full production system.

Manageable complexity - AI coding agents (and humans) work better with bounded, clear requirements than large, complex instructions.

Working code at every step - No long periods where nothing works. Build, test, move forward.

How to Use This Guide

1. Complete the preparation steps below

The preparation section walks you through workspace setup, configuration questions to answer before building, and how to prepare your AI coding agent with the right context.

2. Then read the Architecture Reference

Understanding the system design before building helps you make informed decisions when adapting the guide to your specific needs.

3. Then tackle the stages in order

Each stage builds on the previous one. Don't skip ahead.

4. Use each stage file as a complete prompt to your AI agent

The stage files contain everything your AI coding agent needs to build that stage. Feed the complete file to your AI agent and let it implement.

5. Verify thoroughly before moving on

Test each stage according to its verification steps. Don't move to the next stage until the current one works completely.

6. Expect iteration

Often, something won't work perfectly the first time. That's normal. Read error messages, consult logs, ask your AI agent to help debug. This is part of the learning process.

The Five Stages

Stage 1: Basic API Connection

What you'll build: Simple web page that sends messages to an AI provider and displays responses.

What you'll prove: Your hosting environment works, your API key works, the basic request/response cycle functions correctly.

Components: HTML page, basic JavaScript, PHP API proxy, hardcoded system instruction.

Verification: Type a message, get a response from the AI.

Stage 2: Conversation Storage

What you'll add: Browser-based storage so conversations persist across sessions.

What you'll prove: Students can save conversations, close their browser, come back later, and continue where they left off.

New components: IndexedDB storage via LocalForage, conversation save/load functionality, basic conversation list.

Verification: Create a conversation, close the browser, reopen, and see your conversation still there.

Stage 3: Configuration Files

What you'll add: Move hardcoded values into JSON configuration files. Add server-side instruction assembly.

What you'll prove: Configuration changes take effect without editing code. The foundation for modular instruction building works.

New components: Configuration file, PHP configuration reader, server-side instruction assembly logic.

Verification: Change the system instruction in the config file, create a new conversation, observe the change in AI behavior.

Stage 4: Modular Configuration

What you'll add: Conversation frameworks library, learning supports library, ID-based referencing, conversation instruction snapshots, path-based storage namespacing.

What you'll prove: You can switch between different conversation frameworks and combine different learning supports. Existing conversations maintain their original instructions even when you change the global config.

What are learning supports? Modular instructional strategies that adapt how the AI assists students — like English Language Learner support (simplified vocabulary), chunking (breaking tasks into steps), or Socratic questioning (guiding through questions). These can be mixed and matched with any conversation framework.

New components: Conversation frameworks library file, learning supports library file, enhanced assembly logic, snapshot storage in conversations.

Verification: Create a conversation with one framework, switch to a different framework in config, create another conversation. Confirm both conversations use their respective frozen instructions.

Stage 5: Production Ready

What you'll add: Rate limiting, enhanced error handling, security headers, UI improvements, configuration editor.

What you'll prove: The system is secure, handles errors gracefully, and provides a polished user experience.

New components: Rate limiter, comprehensive error handling, security headers, markdown rendering, keyboard shortcuts, config editor UI.

Verification: Full system test across all features. Intentionally trigger errors and confirm graceful handling.

What You'll Learn

Application Development Skills

Working with AI Coding Agents

Architectural Thinking

Preparation

Before you begin building, set up your workspace, gather necessary resources, and make key technical decisions.

Prerequisites Checklist

Ensure you have:

Technical Decisions

Make these choices before building:

AI Provider

Choose your AI API provider:

Real-world experience: The original Babbleborg uses Google Gemini, which has proven reliable and cost-effective for educational use across multiple classes and subject areas. Gemini Flash models are significantly less expensive than OpenAI or Anthropic while offering robust built-in safety features. That said, all major providers work well — choose based on your budget, feature requirements, and organizational preferences.

Get your API key from your chosen provider and have it ready.

Cost estimation: Use LLM Pricing Calculator to compare current pricing across providers.

Hosting Environment

Document your hosting specifics:

You'll provide these details to your AI coding assistant so it can account for your specific constraints.

Note on alternative platforms: This guide's build stages use PHP/Apache as the implementation example. If your environment uses a different backend stack (Node.js, Python, etc.), the architectural patterns described in the Architecture Reference still apply - you'll work with your AI coding assistant to implement those patterns in your preferred technology. The core requirements remain the same: a secure backend that keeps API keys server-side and proxies requests to your AI provider.

Workspace Setup

1. Create Local Project Directory

mkdir student-ai-chat
cd student-ai-chat

2. Initialize Git Repository

git init

This creates a local version control repository. You'll commit your work at logical points throughout the build process. No GitHub account needed - this is purely local.

3. Create Initial Project Structure

mkdir docs

Complete AI Context Template

The ai-context-template.md file provides your AI coding assistant with essential information about your specific environment and requirements.

Get the template:

  1. Download the template from the AI Context Template page
  2. Save it to your docs/ folder as ai-context-template.md

Fill out all sections with your specific information:

This template captures critical parameters that vary between installations. Your AI assistant will reference this when making implementation decisions.

Editing the template: Use any text editor (VS Code, Sublime Text, Notepad++, etc.). For better readability, markdown editors render the formatting as you edit. Recommended free options:

When to provide it: Include the completed template file when starting each build stage, along with the stage instructions, testing information, and architecture reference.

Preparing Your AI Agent's Reference Library

Your docs/ folder should contain reference materials for your AI coding assistant:

Required:

Optional but helpful:

API Documentation Resources

Your AI agent can reference these online. Optionally save key pages as markdown for offline reference:

Google Gemini:

OpenAI:

Anthropic Claude:

Tools for Saving Webpages as Markdown

If you choose to save documentation pages:

Prepare Testing Content

Simplified System Instruction

During the build process (Stages 1-4), you'll use a simplified system instruction for testing. This proves functionality without overwhelming complexity.

If you'd like something more substantial, save this as a reference (you'll provide it to your AI agent during Stage 1): 

You are an educational AI assistant helping students learn and understand concepts. Your role is to support student learning while maintaining their ownership of the work.

Core principles:
- Guide students to understand concepts rather than simply providing answers
- Ask what students already know before explaining new material
- Break complex ideas into manageable pieces
- Use clear, accessible language
- Provide concrete examples relevant to students' experiences
- Never complete assignments for students - help them complete their own work
- Check for understanding and adjust explanations as needed

Maintain a warm, supportive tone that is direct and honest, balancing support with promoting independence.

This basic instruction creates meaningful educational interactions while you build and test each stage. Feel free to edit this example, but keep in mind that you'll refine and expand your pedagogical approach later in the Making It Yours phase.

Working with Your AI Coding Assistant

Provide Context at Each Stage

When you begin each build stage, you'll provide your AI assistant with:

  1. The stage file itself - Complete instructions for that stage (download from stage page)
  2. Architecture Reference - System design reference (download)
  3. AI Context Template (completed) - Your specific environment and requirements (download)
  4. Testing Guide - For reference during verification steps (download)
  5. Previous stage's code (for stages 2-5)
  6. Optional: Any API or hosting documentation you've saved

The AI Context Template is particularly important - it provides the AI agent with critical information about your deployment environment that affects implementation choices.

AI Agent Roles

Your AI coding assistant will:

You remain responsible for:

Iteration and Debugging

Expect things not to work perfectly on the first try. When errors occur:

  1. Read the error message - Copy the complete error text
  2. Check browser DevTools Console - Look for JavaScript errors
  3. Check server error logs - Most hosting provides error log access
  4. Provide error details to your AI assistant - Include full error messages, relevant log entries, and what you were doing when it failed
  5. Iterate - Your AI assistant will help debug and refine

This is normal and part of the learning process.

Configuration Planning

You don't need to finalize your pedagogical approach before building, but consider:

What's your primary use case?

Who are your students?

What's your educational philosophy about AI?

These questions inform the system instructions, conversation frameworks, and learning supports you'll develop. You don't need final answers now — just start thinking about them.

During Stage 1-3, you'll use the simplified system instruction referenced above. In Stage 4, you'll create basic conversation frameworks and learning supports. After Stage 5, the Making It Yours page will guide you in refining these based on your specific pedagogical approach.

Ready to Build?

Once you've completed this preparation:

  1. ✅ Made technical decisions (API provider, hosting details)
  2. ✅ Set up local workspace with Git
  3. ✅ Created docs/ folder
  4. ✅ Completed ai-context-template.md
  5. ✅ Assembled your AI agent's reference library in docs/ folder

You're ready!

Next step: Read the Architecture Reference to understand the system design, then proceed to Stage 1.