Overview

This PR implements automatic UUID generation for all candidates when they are scraped and added to the database, addressing the need for unique identifiers as requested in the issue.

Problem

Previously, candidates did not have proper unique identifiers in the JSON database. The system relied on name-based matching for candidate lookups, which was fragile and made it difficult to:

• Uniquely identify candidates with similar names
• Build reliable API endpoints for candidate retrieval
• Prepare for future database migration

Solution

Added UUID generation at the point where candidates are created during the scraping process:

1. Candidate Models (app/models/candidate.py)

Added optional id field to all candidate models to store the UUID:

• Candidate: Base model with id: Optional[str] = None
• LokSabhaCandidate: Lok Sabha specific with id: Optional[str] = None
• AssemblyCandidate: Assembly specific with id: Optional[str] = Field(alias="ID", default=None)

2. LokSabha Scraper (app/scrapers/lok_sabha.py)

Modified candidate creation in _scrape_parties() to generate UUID:

party_candidates[party_id].append({
    "id": str(uuid.uuid4()),  # Unique identifier
    "party_id": int(party_id),
    "constituency": constituency,
    "candidate_name": candidate_name,
    # ... other fields
})

3. VidhanSabha Scraper (app/scrapers/vidhan_sabha.py)

Modified candidate creation in _extract_candidates_from_page() to generate UUID:

candidates.append({
    "ID": str(uuid.uuid4()),  # Unique identifier
    "Constituency Code": constituency_code,
    "Name": name,
    "Party": party,
    # ... other fields
})

4. Data Service (app/services/json_data_service.py)

Enhanced get_candidate_by_id() method to support UUID-based lookups while maintaining backward compatibility:

• Primary lookup: Searches by UUID (id or ID field)
• Fallback: Uses original name-based matching if UUID not found

Benefits

✅ Unique Identification: Each candidate now has a globally unique identifier (UUID v4)
✅ Database Ready: Makes future migration to SQL/NoSQL databases seamless
✅ Better APIs: Enables reliable candidate lookup by ID in REST endpoints
✅ Backward Compatible: Existing name-based lookups continue to work
✅ Minimal Impact: Only touched necessary files with surgical changes

Example

When new candidates are scraped, they will automatically include a UUID:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "party_id": 1,
  "constituency": "New Delhi",
  "candidate_name": "John Doe",
  "votes": "100000",
  "margin": "5000"
}

This UUID can then be used in API calls:

GET /api/v1/elections/lok-sabha-2024/candidates/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Testing

• ✅ Verified UUID generation works in both scrapers
• ✅ Confirmed all UUIDs are unique
• ✅ Tested UUID lookup functionality in data service
• ✅ Validated backward compatibility with name-based lookups
• ✅ Code formatted with black and isort

Breaking Changes

None. This is a backward-compatible addition that enhances the system without breaking existing functionality.

Fixes #4

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.