Goal

Move hardcoded values into external JSON configuration files and implement server-side instruction assembly. This transforms your application from a fixed-purpose tool into a flexible system you can reconfigure without editing code.

By the end of this stage, you'll be able to change your system instruction, application title, and other settings simply by editing a configuration file—no code changes required. This is the foundation for the modular configuration system you'll build in Stage 4.

You'll also establish server-side instruction assembly, which is essential for reliable operation on shared hosting environments.

Before You Begin

Pre-flight checklist:

1. Stage 2 is complete and working
2. Review architecture.md sections on "Configuration System" and "System Instruction Assembly Component"
3. Review testing.md for production testing strategies
4. Update your TODO list with Stage 3 tasks

Components to Build

1. Configuration File (JSON)

A JSON file containing all settings that should be configurable without code changes.

Why it exists: Separating configuration from code is a fundamental software design principle. It makes your application maintainable and allows you to adapt it for different classes or subjects without touching the implementation.

What it should contain:

• Application metadata (title, subtitle, version)
• Master enable/disable switch
• AI model identifier
• System instruction text (for now - this becomes modular in Stage 4)
• Student-facing instructions or guidance text
• Any UI customization settings

2. Configuration Handler (Server-Side PHP)

A PHP component that reads the configuration file and makes its values available to other server-side code.

Why it exists: Centralizes configuration loading logic. When you add more configuration files in Stage 4, this handler can coordinate reading multiple sources.

Key capabilities needed:

• Read and parse JSON configuration file
• Validate configuration structure
• Handle missing or malformed configuration gracefully
• Return configuration values to calling code

3. System Instruction Assembly Component (Server-Side PHP)

A component that builds the complete system instruction from configuration server-side.

Why it exists: Keeps instruction assembly on the server. The configuration is read server-side, assembled into the full instruction text, and sent to the AI provider—never transmitted from client to server.

What it does:

• Receives request for system instruction
• Reads configuration to get instruction text
• Returns complete assembled instruction
• (In Stage 4, this will combine multiple sources)

4. Updated API Proxy

Enhance your existing API proxy to use configuration-based system instructions instead of hardcoded text.

Why it exists: The proxy now needs to get the system instruction dynamically rather than using the hardcoded version from Stage 1.

What changes:

• Remove hardcoded system instruction
• Call instruction assembly component to get current instruction
• Use assembled instruction in API request
• Optionally read other config values (model identifier, etc.)

5. Client-Side Configuration Access

Mechanism for client JavaScript to access certain configuration values if needed for UI display or behavior.

Why it exists: Some configuration values (like application title or student instructions) need to be displayed in the browser.

Options:

• Create a separate PHP endpoint that returns public config values as JSON
• Embed select config values in the HTML when page is generated
• Read configuration server-side and pass needed values to client via data attributes

Implementation Tasks

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

Create Configuration Infrastructure

-Design configuration file structure (JSON schema)

-Create configuration file with initial values (migrate hardcoded values from Stage 1)

-Decide on configuration file location (project root, config folder, etc.)

Build Configuration Handler

-Create PHP configuration handler module

-Implement JSON file reading and parsing

-Add validation for required configuration fields

-Handle errors (missing file, invalid JSON, missing required fields)

-Test reading configuration values successfully

Build System Instruction Assembly

-Create PHP component for instruction assembly

-Read system instruction from configuration

-Return complete instruction text

-Handle cases where instruction is missing or invalid

Update API Proxy

-Remove hardcoded system instruction

-Integrate with instruction assembly component

-Use assembled instruction in API requests to provider

-Optionally read model identifier from config instead of hardcoding

-Test that API requests work with configuration-based instructions

Provide Configuration to Client

-Determine which config values need to be accessible from browser

-Create mechanism to expose those values (endpoint, embed, or data attributes)

-Update client JavaScript to use config values where appropriate

-Test that UI displays config-driven values correctly

Migrate All Hardcoded Values

-Identify remaining hardcoded values in your code

-Move them to configuration file

-Update code to read from configuration

-Verify nothing is still hardcoded that should be configurable

Test Configuration Changes

-Change system instruction in config file manually and via UI interface

-Create a new conversation

-Verify the AI behavior reflects the new instruction

-Change application title in config

-Refresh page and verify title appears

-Test with invalid configuration (malformed JSON, missing fields)

-Verify graceful error handling

Success Indicators

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

Configuration Working

• ✓ Application reads settings from JSON configuration file on startup
• ✓ Changing configuration values and reloading shows the changes immediately
• ✓ No code changes required to modify application behavior or appearance
• ✓ UI successfully provides retrieval and editing of JSON file data

System Instruction Assembly

• ✓ New conversations use the system instruction defined in configuration
• ✓ Changing the instruction in config file affects new conversations
• ✓ Existing saved conversations still use their frozen instructions (from Stage 2)

Server-Side Architecture

• ✓ System instruction is assembled server-side, not sent from client
• ✓ Configuration file is never directly accessible to the browser
• ✓ Client receives only the values it needs (title, public instructions, etc.)

Error Handling

• ✓ If configuration file is missing, you see a meaningful error message
• ✓ If configuration JSON is malformed, error handling prevents application crash
• ✓ If required fields are missing, clear error indicates what's needed

No Hardcoded Values Remaining

• ✓ System instruction is in configuration, not code
• ✓ Application title/subtitle is in configuration
• ✓ Model identifier is in configuration (if applicable)
• ✓ Any student-facing text is in configuration

Testing and Verification

Before proceeding to Stage 4:

1. Test configuration changes: Modify several config values, reload, and verify all changes take effect
2. Test instruction updates: Change system instruction, create new conversation, verify AI behavior reflects changes
3. Test saved conversations: Verify previously saved conversations still use their original instructions (not affected by config changes)
4. Test error conditions: Temporarily break the config file (invalid JSON) and verify graceful error handling
5. Code review: Ensure no business logic or content remains hardcoded in your code files

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

What You've Accomplished

With Stage 3 complete, you have:

• Separated configuration from code - fundamental software design principle
• Enabled easy customization - change behavior without editing code
• Established server-side instruction assembly - critical for avoiding WAF restrictions
• Built the foundation for modularity - Stage 4 will extend this to multiple configuration sources

This is a major architectural milestone. Your application is now maintainable and adaptable. Stage 4 will build on this foundation to create a truly modular, pedagogically sophisticated configuration system.

STOP: Before Proceeding to Stage 4

Do not move forward until:

• ✓ All application settings are in configuration file, none hardcoded
• ✓ System instruction assembly works server-side
• ✓ Configuration changes take effect without code modifications
• ✓ Saved conversations maintain their frozen instructions
• ✓ Error conditions are handled gracefully

When Stage 3 is working completely:

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