# 8. Implementation Roadmap

### Phase 1: Foundation (Core Infrastructure)

**Objective:** Establish CLI framework, authentication, and basic tenant management

| Task | Requirements | Complexity |
|------|--------------|------------|
| Set up Python project structure with Typer | - | Low |
| Implement ConfigManager (TOML parsing) | REQ-026-030 | Medium |
| Implement AuthService (MSAL integration) | REQ-031-036 | High |
| Implement token caching and encryption | REQ-031-036 | Medium |
| Add `auth` command group (login, status, logout) | REQ-031-035 | Medium |
| Add `tenants` command group (list, current, switch, add, remove, test) | REQ-026-030 | Medium |
| Implement GraphClient with retry/throttling | - | High |
| Implement strict Pydantic models for all API responses | REQ-042 | Medium |
| Add `api-check` command for contract validation | REQ-043 | Medium |
| Add global flags (--json, --verbose, --tenant) | REQ-037, REQ-040 | Low |
| **Unit tests**: ConfigManager, AuthService, GraphClient (retry/backoff logic) | - | Medium |
| **Integration tests**: Auth flows against test tenant, token caching | - | Medium |
| Set up pytest fixtures and test tenant configuration | - | Low |

### Phase 2: Read Operations (Users, Numbers, Locations)

**Objective:** Enable all read/query operations

| Task | Requirements | Complexity |
|------|--------------|------------|
| Implement UserService with Graph API integration | REQ-001-005 | Medium |
| Add `users` commands (list, show, search) | REQ-001-005 | Medium |
| Implement NumberService with Graph API integration | REQ-006-009 | Medium |
| Add `numbers` commands (list, show, search) | REQ-006-009 | Medium |
| Implement LocationService (CSV reading) | REQ-021-025 | Medium |
| Add `locations` commands (list, show, search) | REQ-021-025 | Low |
| Implement CSV staleness detection | REQ-024 | Low |
| Add rich table output formatting | REQ-038 | Medium |
| **Unit tests**: UserService, NumberService, LocationService (mock Graph responses) | - | Medium |
| **Unit tests**: CSV parsing, staleness detection, user resolution logic | - | Low |
| **Integration tests**: Read operations against test tenant with sample data | - | Medium |
| **Contract tests**: Validate Pydantic models against live API responses | - | Medium |

### Phase 3: Write Operations (Assign, Unassign, Policies)

**Objective:** Enable all modification operations

| Task | Requirements | Complexity |
|------|--------------|------------|
| Implement async operation polling | REQ-010, REQ-012 | High |
| Add `numbers assign` command with E911 enforcement | REQ-010, REQ-011 | High |
| Add `numbers unassign` command | REQ-012 | Medium |
| Add `numbers update` command | REQ-013 | Medium |
| Implement PolicyService | REQ-016-019 | Medium |
| Add `policies` commands (list, show, assign) | REQ-016-019 | Medium |
| Add confirmation prompts and --force flag | REQ-012, REQ-015 | Low |
| Add --dry-run support | REQ-015 | Medium |
| **Unit tests**: Async polling logic, E911 validation, PolicyService | - | Medium |
| **Unit tests**: Dry-run mode, confirmation prompts | - | Low |
| **Integration tests**: Assign/unassign workflows against test tenant | - | High |
| **Integration tests**: Policy assignment, E911 enforcement scenarios | - | Medium |

### Phase 4: Bulk Operations & Polish

**Objective:** Enable bulk operations and production-ready UX

| Task | Requirements | Complexity |
|------|--------------|------------|
| Implement CSV parsing for bulk operations | REQ-014 | Medium |
| Add `numbers bulk-assign` command | REQ-014 | High |
| Add `policies bulk-assign` command | REQ-020 | Medium |
| Implement progress bars | REQ-039 | Medium |
| Add --continue-on-error handling | REQ-014 | Medium |
| Implement results file output | REQ-014 | Low |
| Add debug logging (--debug-log) | REQ-040 | Medium |
| Error message polish and remediation guidance | REQ-041 | Medium |
| **Unit tests**: CSV parsing edge cases, error handling, results file generation | - | Medium |
| **Unit tests**: Progress bar updates, continue-on-error logic | - | Low |
| **Integration tests**: Bulk assign with 100-row CSV against test tenant | - | High |
| **Load tests**: Bulk operations with 1000 rows, validate performance targets | - | Medium |

### Phase 5: Documentation & Release Prep

**Objective:** Production readiness and documentation

| Task | Requirements | Complexity |
|------|--------------|------------|
| Coverage gap analysis and test hardening | - | Medium |
| Create user documentation (CLI reference, tutorials) | - | Medium |
| Create PowerShell export script with documentation | - | Medium |
| Set up daily CI contract tests against test tenant | - | Medium |
| Performance profiling and optimization pass | - | Medium |
| Release packaging (PyPI, standalone binary evaluation) | - | Medium |

---

