# 2. High Level Architecture

### 2.1 Technical Summary

The Teams Phone CLI is a **layered command-line application** built with Python that interfaces with Microsoft Graph API (beta) to manage Teams Phone configurations. The architecture follows a classic three-tier design: CLI commands (Typer), business logic services, and infrastructure/data access components. It uses an **async-capable HTTP client** (httpx) with built-in retry/throttling logic to handle Graph API's rate limits and async operations. Local CSV caching supplements API gaps for emergency locations and policy listings. The design prioritizes **automation and scripting** over interactive use, with multi-tenant support as a first-class feature.

### 2.2 High Level Overview

Based on the PRD Technical Assumptions:

1. **Architectural Style:** Modular Monolith (single deployable CLI with clear internal boundaries)
2. **Repository Structure:** Monorepo (single repo containing CLI, tests, scripts, documentation)
3. **Service Architecture:** Single-process CLI with layered internal services
4. **Primary Data Flow:**
   ```
   User → CLI Commands → Services → Graph API / CSV Cache → Response → Formatted Output
   ```
5. **Key Architectural Decisions:**

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Language | Python 3.10+ | Cross-platform, rich ecosystem, Typer/httpx support |
| CLI Framework | Typer | Modern, type-hinted, auto-completion, excellent DX |
| HTTP Client | httpx | Async support, timeout handling, connection pooling |
| Auth Library | MSAL | Official Microsoft library, handles token refresh |
| Data Validation | Pydantic v2 | Strict mode for contract validation, fast serialization |
| Output Formatting | Rich | Tables, progress bars, color-coded status |

### 2.3 High Level Project Diagram

```mermaid
graph TB
    subgraph "User Environment"
        User[IT Admin / MSP]
        Terminal[Terminal / Script]
    end

    subgraph "Teams Phone CLI"
        CLI[CLI Layer<br/>Typer Commands]

        subgraph "Services"
            UserSvc[UserService]
            NumSvc[NumberService]
            PolSvc[PolicyService]
            LocSvc[LocationService]
            TenantSvc[TenantService]
            AuthSvc[AuthService]
        end

        subgraph "Infrastructure"
            GraphClient[GraphClient<br/>Retry/Throttling]
            CacheMgr[CacheManager<br/>Tokens/Data]
            ConfigMgr[ConfigManager<br/>TOML/Tenants]
            Formatter[OutputFormatter<br/>Tables/JSON]
        end
    end

    subgraph "External Systems"
        GraphAPI[Microsoft Graph API<br/>Beta Endpoints]
        EntraID[Microsoft Entra ID<br/>Authentication]
    end

    subgraph "Local Storage"
        Config[~/.teams-phone/config.toml]
        TokenCache[Token Cache<br/>Encrypted]
        CSVCache[CSV Cache<br/>Locations/Policies]
    end

    User --> Terminal
    Terminal --> CLI
    CLI --> UserSvc & NumSvc & PolSvc & LocSvc & TenantSvc & AuthSvc

    UserSvc & NumSvc & PolSvc --> GraphClient
    LocSvc --> CSVCache
    AuthSvc --> EntraID

    GraphClient --> GraphAPI
    GraphClient --> CacheMgr
    TenantSvc --> ConfigMgr
    ConfigMgr --> Config
    CacheMgr --> TokenCache & CSVCache

    CLI --> Formatter
```

### 2.4 Architectural and Design Patterns

| Pattern | Description | Rationale |
|---------|-------------|-----------|
| **Layered Architecture** | CLI → Service → Infrastructure separation | Clear boundaries, testable services, PRD-specified structure |
| **Repository Pattern** | Services abstract data access (Graph API, CSV) | Enables mocking for tests, future API migration flexibility |
| **Service Layer** | Business logic encapsulated in domain services | Single responsibility, reusable across commands |
| **Async Operations with Polling** | Graph assign/unassign return 202; poll for completion | Required by Graph API design; provides user feedback |
| **Configuration as Code** | TOML-based tenant profiles with env var secrets | Cross-platform, human-readable, security best practice |
| **Strict Schema Validation** | Pydantic models with `extra='forbid'` | Fail-fast on API contract changes (beta API risk mitigation) |
| **Graceful Degradation** | CSV cache optional; warnings when stale/missing | CLI remains functional even without location/policy data |
| **Retry with Exponential Backoff** | 3 retries on 429/503 errors | Graph API throttling resilience per PRD requirements |

---

