# Architecture: Hybrid Graph API + CSV Export

The CLI uses a **hybrid architecture** based on Microsoft Graph API availability:

### Graph API (Real-time)
The following operations use Microsoft Graph API beta endpoints for real-time data:
- **Users**: All operations (`list`, `show`, `search`) via `/admin/teams/userConfigurations`
- **Numbers**: All operations (`list`, `show`, `search`, `assign`, `unassign`, `update`) via `/admin/teams/telephoneNumberManagement/numberAssignments`
- **Policies**: Assignment operations (`assign`, `bulk-assign`) via `/admin/teams/policy/userAssignments/assign`
- **Policies**: User policy viewing via `userConfigurations.effectivePolicyAssignments`

### PowerShell CSV Export (Reference Data)
The following operations **require PowerShell CSV export** because Graph API endpoints do not exist:
- **Locations**: All operations (`list`, `show`, `search`) - no Graph API available
- **Policies**: List available policies (`policies list`) - no Graph API endpoint for listing policy definitions

### CSV Export Requirement

Users must run the PowerShell export script periodically to generate reference data:

```powershell
./Export-TeamsPhoneData.ps1 `
  -TenantId "your-tenant-id" `
  -ApplicationId "your-app-id" `
  -CertificateThumbprint "your-cert-thumbprint" `
  -OutputPath "~/.teams-phone/cache/"
```

**Generated Files:**
- `~/.teams-phone/cache/locations.csv` - Emergency locations
- `~/.teams-phone/cache/policies.csv` - Available policies by type
- `~/.teams-phone/cache/export-metadata.json` - Export timestamp and counts

**Degraded Mode Behavior:**
- If CSV files are missing, commands display a warning but may continue with reduced functionality
- Location validation during number assignment will warn if location ID cannot be verified
- Policy tab completion and validation will be unavailable
- CSV files older than 30 days trigger a staleness warning

**See Also:** `graph-api-contracts.md` Section 7 for detailed CSV schemas and PowerShell cmdlet documentation.

---

