homeschool/DEBUG.md

Debugging the Spelling Practice App

This document provides guidance on debugging and testing the app's data handling functionality.

Testing Tools

1. API Test Page

A user-friendly interface for testing the API endpoints:

• URL: http://localhost:3000/api-test.html
• Features:
  • Test the /getResults endpoint to retrieve session data
  • Create and save new test sessions with customizable parameters
  • View session details for specific users

2. Test Script

A Node.js script to verify the saveResults endpoint functionality:

node test-save-results.js

This script:

1. Verifies the server is running
2. Creates a test session for "testuser"
3. Validates the session was saved correctly
4. Shows summary information about the saved session

Common Issues

File Access Issues

If you're experiencing issues with data storage or retrieval:

1. Check file permissions:

   • Make sure the data directory is writable by the Node.js process
   • In Docker environments, ensure volume mounts are set up correctly

2. Verify file formats:

   • The app expects JSON files in a specific format
   • If manually editing files, validate the JSON structure before restarting

3. Inspect server logs:

   • The server outputs detailed logs with emoji indicators
   • Look for error messages marked with ❌

Session Data Troubleshooting

If sessions aren't appearing correctly:

1. Format compatibility:

   • The app supports multiple data formats for backward compatibility
   • Session data may use either timestamp or date fields
   • Word data may be in answers or words arrays

2. Data verification flow:

   • Save a session using the API test page
   • Check the response from the /saveResults endpoint
   • Verify data using the /getResults endpoint
   • Confirm it appears in the UI

Server Recovery

If the server stops working:

1. Restart the server:

   node server.js
   

2. Check for errors in the logs

3. Data integrity check:

   • Inspect JSON files in the data directory for formatting issues
   • Restore from backups or seed files if needed

Recent Fixes

• Added backup data display when results.json can't be read
• Improved error handling in saveResults endpoint
• Created helper functions to handle different session data formats
• Added SVG clipping paths to fix analytics graph display issues