Purpose of This Document

This document is a reference for AI coding agents building this system. It describes the architectural patterns, system components, and design decisions needed to create a student AI chat interface with complete pedagogical control.

If you're a human reader, this document will help you understand the system design, but it's optimized to provide context to command-line AI coding assistants during implementation.

Implementation note: This document describes architectural patterns conceptually. The build stages in this guide implement these patterns using PHP on shared hosting, but the patterns themselves are platform-agnostic. If you're working with Node.js, Python, or another backend technology, these same architectural decisions and component relationships apply - you'll simply implement them using your platform's idioms and libraries.

System Overview

This is a web-based AI chat application designed for educational use. It allows educators to:

The architecture prioritizes educator autonomy and student privacy.

Core Architectural Decisions

No Authentication System

Why: Privacy, simplicity, and faster deployment. Each installation serves a single class or use case. Students access via URL. No user accounts, passwords, or session management is required, and no chat data is used for model training.

Trade-off: Multiple classes need multiple installations (different URLs or paths).

Local Browser Storage

Why: Student data ownership. Conversations never leave the student's device unless they explicitly export them. No cloud storage, no server-side conversation databases.

Implementation: IndexedDB via LocalForage library.

Server-Side Instruction Assembly

Why: Avoid ModSecurity WAF (Web Application Firewall) restrictions that block large POST payloads. Many shared hosting environments reject requests with very long system instructions.

Solution: Store only IDs in configuration. Server-side PHP assembles the full instruction text from multiple sources before sending to AI provider.

API-Agnostic Design

Why: Let educators choose the AI provider that best fits their needs and budget. Providers have different pricing, capabilities, and policies.

Implementation: Core architecture works with any REST-based LLM API. Requires adapting the API proxy for different request/response formats.

Conversation Instruction Snapshots

Why: Enables modular, curriculum-aligned learning. Teachers can change the system configuration (switch conversation frameworks or learning supports) for new conversations without affecting existing student work.

Implementation: Each conversation stores a complete copy of the system instruction that was active when it was created.

Pedagogical benefit: Week 1 students create "brainstorming" conversations, Week 2 teacher switches mode to "project planning" - students can still access and continue their Week 1 brainstorming conversations while new conversations use the planning framework.

System Components

Configuration System

Three JSON files work together to provide flexible, modular configuration:

1. Main Configuration File

2. Conversation Frameworks Library File

3. Learning Supports Library File

Why this structure:

System Instruction Assembly Component

A server-side PHP component that dynamically builds complete system instructions.

Process:

  1. Receives configuration (or conversation-specific instruction if resuming saved conversation)
  2. If building fresh instruction:
  3. Reads main config file for core framework
  4. Looks up selected conversation framework by ID from frameworks library
  5. Looks up selected learning supports by IDs from supports library
  6. Retrieves any framework-specific customization notes
  7. Combines all components into single complete instruction
  8. Returns assembled instruction for use in API request

Output includes:

Why server-side:

API Proxy Layer

A PHP backend component that mediates between the client and the AI provider API.

Responsibilities:

Request Handling:

Rate Limiting:

Error Handling & Retry Logic:

Response Handling:

Security:

Why a proxy:

Storage Layer

Browser-based storage using IndexedDB via the LocalForage library.

Storage Model:

Conversation Object Structure:

Why this structure:

Path-Based Namespacing:

Automatic Limit Management:

Why browser storage:

UI Components

Chat Interface:

Conversation Management:

Configuration Editors (Optional):

Two modes possible, for use by teachers:

Both editors:

Why separate editors:

Data Flow Diagrams

Request Flow

sequenceDiagram
    participant User
    participant UI
    participant Storage
    participant API Proxy
    participant AI Provider

    User->>UI: Enter message
    UI->>Storage: Check for saved conversation
    Storage-->>UI: Return conversation + instruction (if exists)
    UI->>API Proxy: Send message + history + instruction
    API Proxy->>API Proxy: Assemble or use provided instruction
    API Proxy->>AI Provider: Format & send request
    AI Provider-->>API Proxy: Return response + token usage
    API Proxy-->>UI: Return formatted response
    UI->>UI: Display response with markdown
    UI->>Storage: Save conversation (if requested)
    Storage-->>UI: Confirm saved

Configuration Assembly

flowchart TD
    A[New Conversation Request] --> B{Has saved instruction?}
    B -->|Yes| C[Use conversation snapshot]
    B -->|No| D[Read main config]
    D --> E[Get core framework]
    D --> F[Get selected framework ID]
    D --> G[Get selected support IDs]
    F --> H[Look up framework in library]
    G --> I[Look up supports in library]
    E --> J[Combine all components]
    H --> J
    I --> J
    J --> K[Complete system instruction]
    C --> L[Send to AI provider]
    K --> L

Storage Architecture

flowchart TD
    A[Browser IndexedDB] --> B[Namespace: /class-path/]
    B --> C[Conversation 1]
    B --> D[Conversation 2]
    B --> E[... up to 15]
    C --> F[ID, Title, Timestamps]
    C --> G[Messages Array]
    C --> H[System Instruction Snapshot]
    C --> I[Metadata]

    J[New Conversation Save] --> K{At 15 limit?}
    K -->|Yes| L[Find oldest by timestamp]
    K -->|No| M[Save directly]
    L --> N[Prompt user to Delete]
    N --> M

Security Considerations

API Key Protection

Input Validation

Input Sanitization

Security Headers

Rate Limiting

SSL/TLS

Trade-offs and Alternatives

No Authentication

Trade-off: Anyone with the URL can access. Suitable for classroom environments where URL is shared only with enrolled students.

Alternative considered: User accounts with authentication. Rejected due to complexity, privacy concerns (storing student data), and deployment overhead.

Browser Storage Limit (15 conversations)

Trade-off: Students must delete old conversations to create new ones.

Alternative considered: Unlimited storage. Rejected due to browser storage quotas and UX complexity of managing large conversation lists.

Mitigation: Students can export conversations before deletion.

Server-Side Configuration Files

Trade-off: Requires server access to change configuration. Not suitable for non-technical users without file access.

Alternative considered: Database-backed configuration. Rejected due to deployment complexity and shared hosting limitations.

Mitigation: Configuration editors provide UI for file editing.

Single Installation Per Use Case

Trade-off: Multiple classes need multiple installations (different paths or subdomains).

Alternative considered: Multi-tenant system with class/student management. Rejected due to authentication requirements and complexity.

Benefit: Simplicity, privacy, isolation between classes.

Deployment Considerations

Hosting Requirements

External Dependencies

No Database Required