discourse/backend/identity/README.md

# Identity Verification System

This module implements a modular identity verification system for VoxPop, allowing verification of users from different countries using country-specific verification methods.

## Design

The system is built around the following components:

1. **VerificationProvider Interface**: Defines the contract for all country-specific verification providers
2. **Country-Specific Providers**: 
   - `USVerificationProvider` - Implements US-specific verification using Privado ID
   - `PlaceholderVerificationProvider` - Used for countries without specific implementation
3. **VerificationService**: Manages verification process and provider registration
4. **HTTP Handler**: Exposes the verification API

## API Endpoints

### Verify Identity

**Endpoint**: `POST /verify`

**Request Body**:
```json
{
  "country": "US",
  "userData": {
    "privadoProof": "user-privado-proof-12345"
  },
  "selfAttestedEligible": "true"
}
```

**Response**:
```json
{
  "status": "Fully Eligible",
  "citizenshipVerified": true,
  "eligibilityVerified": true
}
```

## Status Levels

- **Unverified**: User has not passed any verification
- **Verified**: User's citizenship is verified but not necessarily eligible
- **Fully Eligible**: User is both verified and eligible to participate

## Example Usage

### US Verification

```json
// Request
{
  "country": "US",
  "userData": {
    "privadoProof": "user-privado-proof-12345"
  },
  "selfAttestedEligible": "true"
}

// Response
{
  "status": "Fully Eligible",
  "citizenshipVerified": true,
  "eligibilityVerified": true
}
```

### Partially Verified US User (Citizenship only)

```json
// Request
{
  "country": "US",
  "userData": {
    "privadoProof": "user-privado-proof-12345"
  },
  "selfAttestedEligible": "false"
}

// Response
{
  "status": "Verified",
  "citizenshipVerified": true,
  "eligibilityVerified": false
}
```

### Other Country Verification

```json
// Request
{
  "country": "CA",
  "userData": {}
}

// Response
{
  "status": "Fully Eligible",
  "citizenshipVerified": true,
  "eligibilityVerified": true
}
```

## Adding New Providers

To add a new country-specific provider:

1. Create a new type that implements the `VerificationProvider` interface
2. Update the `GetVerificationProvider` function to return your provider for the appropriate country code

Example:

```go
// CanadaVerificationProvider implements verification for Canadian citizens
type CanadaVerificationProvider struct{}

func (p *CanadaVerificationProvider) VerifyCitizenship(userData map[string]string) (bool, error) {
    // Canada-specific verification logic
    return true, nil
}

func (p *CanadaVerificationProvider) VerifyEligibility(userData map[string]string) (bool, error) {
    // Canada-specific eligibility logic
    return true, nil
}

func (p *CanadaVerificationProvider) GetCountry() string {
    return "CA"
}

// Update the factory function
func GetVerificationProvider(country string) VerificationProvider {
    switch country {
    case "US":
        return &USVerificationProvider{}
    case "CA":
        return &CanadaVerificationProvider{}
    default:
        return NewPlaceholderVerificationProvider(country)
    }
}
```