Backup Data System

Overview

The Backup Data System provides a fallback mechanism for API endpoints when the MongoDB database connection fails or returns errors. This ensures that critical API endpoints (particularly those in headmaster.py) remain functional during database outages or connectivity issues, improving the overall reliability and availability of the application.

Purpose

• Maintain Service Availability: Ensures that API endpoints continue to function even when the database is unavailable
• Prevent Cascading Failures: Isolates database failures to prevent them from affecting the entire application
• Improve User Experience: Users continue to receive responses rather than facing error messages during database outages
• Support Testing and Development: Provides consistent data for development and testing environments

How It Works

The system consists of two main components:

1. backup_data.py: Contains sample datasets for critical entities (teachers, headmasters, schools, etc.)
2. db_fallback.py: Provides wrapper functions around MongoDB operations that fall back to backup data when database operations fail

Architecture

┌───────────────┐     ┌───────────────┐    ┌─────────────┐
│ API Endpoints │────►│ DB Fallback   │───►│ MongoDB     │
│ (headmaster.py)│     │ (db_fallback.py)│    │ Database    │
└───────────────┘     └───┬───────────┘    └─────────────┘
                          │ (on failure)
                          ▼
                     ┌────────────────┐
                     │ Backup Data    │
                     │ (backup_data.py)│
                     └────────────────┘

Process Flow

1. API endpoint makes a database request using the db_fallback functions
2. The system attempts to execute the request against the MongoDB database
3. If the database operation succeeds, the real data is returned
4. If the database operation fails (connection issues, timeout, etc.), the system retrieves the corresponding backup data
5. The backup data is returned to the API endpoint, which continues processing as normal

Usage

To use the backup data system in your API endpoints:

# Instead of directly importing from database
# from app.model.database import db

# Import the fallback module
from app.services.db_fallback import find_one, find, insert_one, update_one

# Use the fallback functions just like you would use MongoDB functions
async def get_headmaster(headmaster_id):
    headmaster = await find_one("headmasters", {"_id": ObjectId(headmaster_id)})
    return headmaster

Maintaining Backup Data

Updating Backup Data

The backup data should be periodically updated to reflect the current state of the production database:

1. Extract a representative sample of data from each collection
2. Sanitize the data (remove sensitive information, use test emails/phone numbers)
3. Update the corresponding variables in backup_data.py

Example of updating backup data:

# app/services/backup_data.py
# Update the TEACHERS list with new sample data
TEACHERS = [
    {
        "_id": {"$oid": "67d422907c920fa21185bc46"},
        "first_name": "TEST",
        "last_name": "NAME",
        # Add other fields...
    },
    # Add more teacher records...
]

Adding New Entity Types

To add backup data for a new entity type:

1. Create a new list variable in backup_data.py with sample data
2. Add a corresponding getter function
3. Update db_fallback.py to handle the new entity type

Best Practices

1. Keep Backup Data Minimal: Include only enough records to support critical functionality
2. Use Realistic Data: Ensure backup data represents realistic scenarios but doesn't contain actual user data
3. Update Regularly: Refresh backup data periodically to match schema changes and current data patterns
4. Test Fallback Scenarios: Regularly test that the system works correctly when the database is unavailable
5. Monitor Usage: Log when backup data is used to track database issues and ensure they're addressed

Limitations

• Backup data is read-only and static
• Write operations (insert, update, delete) will appear to succeed but won't persist after service restart
• Complex queries may not be fully supported with backup data
• The backup data is a limited subset and may not cover all edge cases

Troubleshooting

If API endpoints are returning unexpected results during database outages:

1. Check that the backup data for the relevant entity is up-to-date
2. Verify that the API endpoint is using the db_fallback functions
3. Examine logs for any errors in the fallback mechanism
4. Ensure the backup data structure matches what the API expects

Contributing

When making changes to the backup data system:

1. Update both the backup data and the fallback mechanisms together
2. Test thoroughly with both working and non-working database connections
3. Document any new backup data sets or fallback functions
4. Update this README with any architectural changes