🐛 Fix inconsistent field naming: avatar vs imageUrl across backend services

[Devasy]

🐛 Bug Report: Inconsistent Field Naming - avatar vs imageUrl

Problem Description

There is a critical inconsistency in the backend codebase where user profile images are referenced using two different field names:

• avatar (used in auth service and schemas)
• imageUrl (used in user service and schemas)

This inconsistency causes confusion, potential data corruption, and makes the API behavior unpredictable for frontend consumers.

Current State Analysis

Files using avatar:

• backend/app/auth/schemas.py - Line 36: avatar: Optional[str] = None
• backend/app/auth/service.py - Lines 96, 185, 186, 199: User creation and Google auth
• backend/app/groups/service.py - Lines 42, 46, 59: Group member enrichment

Files using imageUrl:

• backend/app/user/schemas.py - Lines 10, 17: imageUrl: Optional[str] = None
• backend/app/user/service.py - Line 38: Response mapping with fallback logic
• backend/tests/user/ - Multiple test files using imageUrl

Fallback Logic Found:

# In user/service.py line 38
"imageUrl": user.get("imageUrl") or user.get("avatar")

# In groups/service.py line 42
"avatar": user.get("imageUrl") or user.get("avatar") if user else None

Database Schema Documentation:

According to docs/nonrelational-database-schema.md, the intended field name is imageUrl.

Impact

1. API Inconsistency: Different endpoints return user data with different field names
2. Frontend Confusion: Clients don't know which field to expect
3. Data Integrity: Users might have both fields populated with different values
4. Maintenance Overhead: Fallback logic scattered across codebase
5. Testing Issues: Tests use different field names

Proposed Solution

Standardize on imageUrl as the canonical field name across the entire backend, as specified in the database schema documentation.

Acceptance Criteria

📋 Phase 1: Code Standardization

• Auth Service: Update auth/schemas.py to use imageUrl instead of avatar
• Auth Service: Update auth/service.py to use imageUrl in all user creation and update operations
• Groups Service: Update groups/service.py to use imageUrl when enriching member data
• Database Operations: Ensure all database queries and updates use imageUrl
• Response Models: Verify all API response models consistently use imageUrl

📋 Phase 2: Database Migration

• Migration Script: Create a database migration script that:
  • Identifies users with avatar field but no imageUrl field
  • Copies avatar values to imageUrl field
  • Removes the deprecated avatar field from all user documents
  • Logs migration statistics and any conflicts found
• Backup Strategy: Document backup procedures before migration
• Rollback Plan: Create rollback script in case migration needs to be reversed

📋 Phase 3: Testing & Validation

• Unit Tests: Update all tests to use imageUrl consistently
• Integration Tests: Verify API endpoints return consistent field names
• Migration Tests: Test migration script with sample data
• Backward Compatibility: Ensure no breaking changes for existing API consumers

📋 Phase 4: Documentation & Cleanup

• API Documentation: Update all API docs to reflect imageUrl usage
• Code Cleanup: Remove all fallback logic (user.get("imageUrl") or user.get("avatar"))
• Schema Validation: Add Pydantic validators if needed to ensure data consistency
• Migration Documentation: Document the migration process and results

Technical Requirements

Migration Script Specifications

The migration script should:

1. Pre-migration Validation:

   • Count total users with avatar field
   • Count users with both avatar and imageUrl fields
   • Identify potential conflicts (different values in both fields)

2. Migration Process:

   • For users with only avatar: Copy to imageUrl and remove avatar
   • For users with both fields: Keep imageUrl (as it's the canonical field) and remove avatar
   • For users with neither: No action needed

3. Post-migration Validation:

   • Verify no avatar fields remain in user documents
   • Confirm all valid image URLs are preserved in imageUrl field
   • Generate migration report with statistics

4. Error Handling:

   • Graceful handling of connection issues
   • Rollback capability if migration fails
   • Detailed logging of all operations

Files to Modify

backend/app/auth/schemas.py
backend/app/auth/service.py  
backend/app/groups/service.py
backend/app/user/service.py (cleanup fallback logic)
backend/tests/auth/test_auth_routes.py
backend/tests/auth/test_auth_service.py
All other test files using avatar field

Migration Script Location

backend/migrations/
├── migrate_avatar_to_imageurl.py
├── rollback_avatar_migration.py
└── README.md

Definition of Done

• All backend code uses imageUrl consistently
• Database migration completed successfully
• All tests pass with updated field names
• API documentation updated
• Migration scripts tested and documented
• No breaking changes for existing API consumers
• Code review completed and approved

Priority: High 🔴

This issue affects data consistency and API reliability across the entire application.

Estimated Effort: 2-3 days

• Day 1: Code standardization and testing
• Day 2: Migration script development and testing
• Day 3: Documentation, final testing, and deployment

---

Assignee: vraj patel (vrajpatel195)
Labels: bug, backend, database, gssoc25, level3

[Devasy]

@vrajpatelll You're assigned to this issue as part of GSSoC 25 Level 3.

This is a critical backend issue that affects data consistency across our API. The task involves:

1. Code Standardization - Updating all backend services to use imageUrl consistently
2. Database Migration - Creating migration scripts to clean up existing data
3. Testing - Ensuring all tests pass and API behavior is consistent
4. Documentation - Updating docs and cleaning up fallback logic

Please confirm your availability and let me know if you have any questions about the requirements. The estimated timeline is 2-3 days, and this will help improve the overall data integrity of the Splitwiser backend.

Looking forward to your contribution! 🚀

[Aryant-Tripathi]

Hey @Devasy23, is this issue available to pick, as Vraj is already working on issue 70?
I will go through the requirements and try to fix it.