# Facility Status & Verification System - Conceptual Design

## Overview

The Geezer Guide platform uses a **dual-control system** for facility management with two independent but complementary fields:

1. **`status`** - Operational control
2. **`verified`** - Trust/quality badge

## Field Definitions

### Status Field (Operational Control)
```typescript
status: 'active' | 'pending' | 'suspended' | 'closed' | 'rejected'
```

**Purpose**: Controls whether a facility is operationally allowed on the platform.

| Status | Meaning | Visibility | User Actions |
|--------|---------|------------|--------------|
| `pending` | Newly submitted, awaiting admin review | ❌ Hidden from public | ❌ Cannot interact |
| `active` | Approved and operational | ✅ Visible to all users | ✅ Can view, favorite, review |
| `suspended` | Temporarily disabled | ❌ Hidden from public | ❌ Cannot interact |
| `rejected` | Permanently denied | ❌ Hidden from public | ❌ Cannot interact |
| `closed` | Facility no longer operates | ❌ Hidden from public | ❌ Cannot interact |

### Verified Field (Trust Badge)
```typescript
verified: true | false
```

**Purpose**: Indicates admin-confirmed legitimacy and quality verification.

| Verified | Meaning | Visual Indicator | Search Impact |
|----------|---------|------------------|---------------|
| `true` | Admin verified legitimacy | ✅ "Verified" badge shown | 📈 Higher search ranking |
| `false` | Not yet verified | No badge | 📉 Lower search ranking |

## Why Two Separate Fields?

### Real-World Analogy: Restaurant Platform

```
Restaurant A:
├─ Status: Active (can accept orders)
├─ Verified: true (health inspection passed, license confirmed)
└─ Shows: ✅ Open for business + ✅ Verified badge

Restaurant B:
├─ Status: Active (can accept orders)
├─ Verified: false (new, verification pending)
└─ Shows: ✅ Open for business + No verification badge

Restaurant C:
├─ Status: Suspended (health code violation)
├─ Verified: true (was previously verified)
└─ Shows: ❌ Not accepting orders (even though was verified)
```

## Common Scenarios

### Scenario 1: New Facility Onboarding

```
Day 1: Facility owner creates listing
├─ status: 'pending'
├─ verified: false
└─ Result: Hidden, awaiting admin approval

Day 2: Admin approves listing
├─ status: 'active' ← Changed by admin
├─ verified: false ← Still unverified
└─ Result: Visible to users, no badge

Day 7: Admin verifies facility
├─ status: 'active'
├─ verified: true ← Changed by admin
└─ Result: Visible + Verified badge shown
```

### Scenario 2: Policy Violation

```
Active Verified Facility violates policy:

Before Suspension:
├─ status: 'active'
├─ verified: true
└─ Result: ✅ Visible + ✅ Badge

After Suspension:
├─ status: 'suspended' ← Changed
├─ verified: true ← Unchanged (still trustworthy when reactivated)
└─ Result: ❌ Hidden from public

After Issue Resolved:
├─ status: 'active' ← Restored
├─ verified: true ← Retained
└─ Result: ✅ Visible + ✅ Badge (no need to re-verify)
```

### Scenario 3: Verification Removed

```
Facility license expires or issues found:

├─ status: 'active' ← Unchanged (can still operate)
├─ verified: false ← Removed by admin
└─ Result: ✅ Visible but ❌ No badge (users see but are warned)
```

## What Happens When You Suspend?

### Immediate Effects:
1. **Frontend Display**:
   - ❌ Facility disappears from public search results
   - ❌ Detail page shows "This facility is currently unavailable"
   - ❌ Cannot be favorited or reviewed

2. **Database**:
   ```typescript
   facility.status = 'suspended'
   facility.rejectionReason = "Reason provided by admin"
   ```

3. **Owner Notification**:
   - 📧 Email sent to facility owner
   - 📱 In-app notification (if implemented)
   - 📋 Reason for suspension visible in owner dashboard

4. **Verification Status**:
   - ✅ `verified` field remains **unchanged**
   - 💡 Rationale: Suspension is temporary; verification stays valid

### Why Verification Isn't Removed on Suspension:

```
Suspension Reasons ≠ Legitimacy Issues

✅ Good reasons to keep verification:
├─ Late payment
├─ Temporary policy violation
├─ Incomplete documentation
├─ Owner request
└─ System maintenance

❌ Reasons to remove verification:
├─ License revoked
├─ Fraudulent information
├─ Health/safety violations
└─ Legal issues
```

## Real-World Platform Comparisons

### Airbnb Model:
- **Listed** = Active status
- **Superhost** = Verified badge
- Superhosts can be temporarily suspended but retain badge

### Yelp Model:
- **Claimed Business** = Active status
- **Yelp Verified** = Trust badge
- Businesses can be active without verification

### Google Maps Model:
- **Open/Operational** = Active status
- **Google Verified** = Ownership confirmed
- Places can be open without verification

## Benefits of This Design

### 1. **Flexibility**
- Admin can control visibility independently from trust
- Temporary issues don't require re-verification

### 2. **User Experience**
```
Active + Verified = ⭐⭐⭐⭐⭐ Highest trust
Active + Unverified = ⭐⭐⭐ Medium trust (new, still building reputation)
Suspended + Any = ❌ Not accessible
```

### 3. **Admin Control**
- Quick actions: Suspend/Activate (operational)
- Careful actions: Verify/Unverify (trust)

### 4. **Business Logic**
```typescript
// Public facility query
const facilities = await Facility.find({
  status: 'active', // Must be active
  // verified can be true or false
}).sort({
  verified: -1, // Verified facilities ranked higher
  rating: -1
})
```

## Data Model Structure

```typescript
interface IFacility {
  // ... other fields ...
  
  // Operational Status
  status: 'active' | 'pending' | 'suspended' | 'closed' | 'rejected'
  
  // Trust Badge
  verified: boolean
  
  // Audit Trail
  approvedAt?: Date
  approvedBy?: ObjectId
  rejectedAt?: Date
  rejectedBy?: ObjectId
  rejectionReason?: string
  
  // Timestamps
  createdAt: Date
  updatedAt: Date
}
```

## API Endpoints

### Status Management
```typescript
PUT /api/admin/facilities/:id/status
Body: { status: 'active' | 'suspended', reason?: string }
Effect: Changes operational availability
```

### Verification Management
```typescript
PUT /api/admin/facilities/:id/verify
Body: { verified: true | false }
Effect: Adds/removes trust badge
```

## Admin Decision Tree

```
Is the facility legitimate? → Verify
Is the facility approved to operate? → Set Active
Does facility violate policy? → Suspend (but keep verified)
Did facility provide fake info? → Unverify + Suspend
Is facility permanently closed? → Set Closed
```

## Search & Display Logic

### Frontend Display Rules:
```typescript
if (facility.status === 'active') {
  // Show in search results
  
  if (facility.verified) {
    // Display: ✅ Verified badge
    // Ranking: Higher in search
  } else {
    // Display: No badge
    // Ranking: Lower in search
    // Note: "Verification pending"
  }
  
} else {
  // Don't show in public search
  // Owner can see in dashboard with status indicator
}
```

## Conclusion

The dual-field system provides:
- ✅ **Operational flexibility** (suspend/reactivate quickly)
- ✅ **Trust differentiation** (verified vs unverified)
- ✅ **User transparency** (clear indicators of facility status)
- ✅ **Admin efficiency** (independent controls for different purposes)

This design follows industry best practices and provides a robust foundation for marketplace trust and safety.