Goal

Add browser-based persistent storage so conversations survive browser sessions. Students can save their work, close their browser, return later, and continue exactly where they left off.

This stage transforms your basic chat interface into a tool students can actually use over time. Without storage, every browser refresh loses the conversation—not useful for sustained learning. With storage, students build a library of conversations they can revisit and continue.

You'll implement IndexedDB storage (via the LocalForage library), conversation save/load functionality, and a basic conversation list interface.

Before You Begin

Pre-flight checklist:

1. Stage 1 is complete and working
2. Review architecture.md sections on "Storage Layer" and conversation object structure
3. Review testing.md for production testing strategies
4. Update your TODO list with Stage 2 tasks

Components to Build

1. Storage Manager

A JavaScript module that handles all interactions with browser storage (IndexedDB). This abstracts the complexity of IndexedDB behind simple functions like saveConversation() and loadConversation().

Why it exists: IndexedDB is powerful but complex. A storage manager provides a clean interface for the rest of your code. It also centralizes storage logic—when you add path namespacing in Stage 4, you'll only update this one component.

Key capabilities needed:

• Initialize IndexedDB connection
• Save conversation objects (with all their data)
• Load conversations by ID
• List all saved conversations
• Delete conversations

2. Conversation Object Structure

A standardized data structure that represents a complete conversation with all necessary metadata.

Why it exists: Consistent structure makes storage, retrieval, and display predictable. As defined in architecture.md, each conversation needs: unique ID, title, timestamps, message array, and metadata.

What it must include:

• Unique identifier
• User-editable title
• Creation timestamp and last-updated timestamp
• Complete message history (array of message objects with role and content)
• Any metadata needed for display or filtering

3. Conversation Management UI

Interface elements that let users save, load, and manage their conversations.

Why it exists: Students need to see what conversations they have, open the ones they want, and delete old ones to make room for new work.

What it must provide:

• Button or control to save current conversation
• List of saved conversations showing titles and relevant metadata
• Click to load a conversation (restores full context)
• Delete conversation control
• Indicator showing which conversation is currently active

4. Enhanced Chat Interface

Extend your Stage 1 interface to work with the storage system.

Why it exists: The chat interface needs to know whether it's working with a new conversation or a saved one, and handle both cases appropriately.

What needs to change:

• Track current conversation ID (if loaded from storage)
• When loading a conversation, populate the interface with its message history
• When sending new messages, update the conversation's message array
• Provide save functionality (auto-save recommended - students won't remember to save manually)

5. Initial AI Greeting

Automatically trigger an AI greeting when a new conversation starts.

Why it exists: Students shouldn't face a blank interface. The AI should initiate the conversation with a welcoming message.

How it works:

• When a new conversation is created, automatically send a hidden user message to the API (e.g., "Hello?")
• This hidden message is not displayed to the student in the interface
• The API responds with the AI's actual greeting
• Student only sees the AI's greeting - appears that AI initiated the conversation
• Uses the normal request/response flow (no special handling needed)

Implementation approach:

• On new conversation load, send initial API request with simple trigger message
• Don't display the trigger message in the chat interface
• Display only the AI's response
• Message history starts with AI greeting (trigger message omitted from display)

Implementation Tasks

Update your TODO list with these tasks and track progress as you work.

Set Up Storage Infrastructure

• Include LocalForage library (CDN or local copy)
• Create storage manager module
• Initialize IndexedDB connection with appropriate database name
• Test that browser storage is accessible and working

Define Conversation Data Structure

• Design conversation object with all required fields
• Create function to generate unique conversation IDs
• Create function to initialize new conversation objects

Implement Core Storage Functions

• Save conversation to IndexedDB
• Load conversation by ID from IndexedDB
• Retrieve list of all saved conversations
• Delete conversation by ID
• Handle storage errors gracefully

Build Conversation Management UI

• Create conversation list display area
• Show all saved conversations with titles and timestamps
• Implement click-to-load functionality
• Add delete button/control for each conversation
• Show which conversation is currently active
• Add "new conversation" control

Integrate Storage with Chat Interface

• Track whether current conversation is new or loaded
• When loading conversation, restore all messages to display
• When sending messages, add them to current conversation's message array
• Implement auto-save after each message exchange
• Update conversation's last-updated timestamp when modified
• Optionally add manual save button as well for immediate user control

Handle Edge Cases

• What happens when user tries to load a conversation while already in one?
• How does "new conversation" work if there are unsaved changes?
• What if storage quota is exceeded?

Test the Complete Flow

• Create a new conversation and exchange several messages
• Save the conversation
• Refresh the browser
• Load the conversation and verify all messages appear
• Add more messages to the loaded conversation
• Save again and verify updates persist
• Create multiple conversations and verify they're all stored independently
• Delete a conversation and verify it's gone

Success Indicators

When Stage 2 is complete, you should observe these behaviors:

Basic Storage Working

• ✓ You can create a conversation with multiple messages
• ✓ Each message exchange automatically saves
• ✓ After refreshing the browser, your conversation appears in the list with all messages
• ✓ Clicking a saved conversation loads all its messages into the interface
• ✓ You can continue a loaded conversation by sending more messages

Multiple Conversations

• ✓ You can create and save multiple different conversations
• ✓ Each conversation maintains its own separate message history
• ✓ Switching between conversations shows the correct messages for each
• ✓ The interface clearly indicates which conversation is currently active

Conversation Management

• ✓ You can delete conversations and they disappear from the list
• ✓ Starting a new conversation clears the interface for fresh messages
• ✓ Conversation titles are displayed (either user-created or auto-generated)
• ✓ Timestamps help identify when conversations were created or last modified

Data Persistence

• ✓ Conversations survive browser refresh
• ✓ Conversations survive browser close and reopen
• ✓ All messages within a conversation are preserved exactly as entered
• ✓ Metadata (timestamps, titles) persists correctly

User Experience

• ✓ Auto-save happens seamlessly without requiring user action
• ✓ The interface makes it obvious how to load and manage conversations
• ✓ Error conditions (like storage failures) display helpful messages

Testing and Verification

Before proceeding to Stage 3:

1. Test persistence: Create conversations, close the browser completely, reopen, and verify everything is still there
2. Test multiple conversations: Create at least 3-5 different conversations and verify they remain independent
3. Test editing: Load a conversation, add messages, save again, reload, and verify updates persisted
4. Test deletion: Delete conversations and confirm they're removed from storage
5. Check browser DevTools: Open Application/Storage tab and inspect IndexedDB to see your conversation data
6. Test storage limits: Verify behavior if you create many conversations (does your code handle limits gracefully?)

Consult TESTING.md for additional verification strategies and troubleshooting guidance.

What You've Accomplished

With Stage 2 complete, you have:

• Made the application actually useful for sustained learning work
• Implemented browser-based data persistence without server-side database complexity
• Created conversation management that lets students organize their work
• Built a foundation for namespacing (coming in Stage 4) and multi-conversation workflows

Students can now use this tool over weeks or months, building up a library of learning conversations they can revisit. This is the point where the application becomes genuinely valuable for educational use.

STOP: Before Proceeding to Stage 3

Do not move forward until:

• ✓ Conversations save successfully and persist across browser sessions
• ✓ You can create, load, continue, and delete multiple conversations
• ✓ The interface clearly shows which conversation is active
• ✓ You've tested with multiple conversations and verified they remain independent
• ✓ All edge cases are handled gracefully

When Stage 2 is working completely:

1. Update your TODO list - mark Stage 2 tasks complete, add any notes or learnings
2. Create a git commit with your working Stage 2 code
3. Update any other contextual documents you're maintaining
4. Proceed to stage-3-context.md