# TenantFleet Architecture

## Overview

TenantFleet is a multi-tenant Microsoft Entra ID governance platform built on three principles:

1. **Zero secrets** — OIDC workload identity federation everywhere
2. **Tenant isolation** — Row-level security, not database-per-tenant
3. **GitOps** — All configuration is code, all changes are PR-reviewed

## System Diagram

```
                    GitHub Actions (CI/CD)
                           |
                           v
              +---------------------------+
              |  OIDC Token Exchange      |
              |  (federated credentials)  |
              +---------------------------+
                           |
            +--------------+--------------+
            |              |              |
    User-Assigned      User-Assigned   User-Assigned
    Managed Identity     Managed Identity  Managed Identity
    (Staging)            (Production)      (CI)
            |              |              |
            +--------------+--------------+
                           |
            +--------------+--------------+
            |              |              |
     Control Tower   Domain Intel.   User Lifecycle
     (Python)        (Python)        (PowerShell)
            |              |              |
    +-------+-------+  +---+---+      +---+------------------+
    |       |       |  |   |   |      |   |   |   |   |   |
   SQL   Graph   ARM  SQL Graph DNS  Graph Exch  SP  OD  Grp
```

## Components

### Control Tower

**Language:** Python 3.12 + FastAPI  
**Database:** Azure SQL (shared, row-level isolation)  
**Purpose:** Cross-tenant governance dashboard

Key services:
- `cost_service` — aggregates Azure cost data per tenant
- `compliance_service` — tracks security posture (MFA, DMARC, etc.)
- `identity_service` — user lifecycle monitoring
- `monitoring_service` — sync health and alerting

### Domain Intelligence

**Language:** Python 3.12 + FastAPI  
**Purpose:** DNS/email security monitoring

Key services:
- `dmarc_service` — DMARC policy monitoring
- `dns_service` — DNS record change tracking
- `email_security_service` — DKIM/SPF validation
- `domain_monitor` — domain expiration and health

### User Lifecycle

**Language:** PowerShell 7 + Microsoft Graph SDK  
**Purpose:** Automated user onboarding/offboarding

Key scripts:
- `New-UserAccount.ps1` — create Entra user
- `Invoke-FullOffboard.ps1` — complete offboarding orchestration
- `Connect-Tenant.ps1` — OIDC auth to Graph + Exchange

## Data Isolation

```sql
-- Every table has a tenant_id column
CREATE TABLE users (
    id UUID PRIMARY KEY,
    tenant_id TEXT NOT NULL,
    upn TEXT NOT NULL,
    display_name TEXT,
    ...
);

CREATE INDEX idx_users_tenant ON users(tenant_id);

-- Middleware enforces scope
SELECT * FROM users WHERE tenant_id = :current_tenant_id;
```

## Authentication Flow

```
1. GitHub Actions workflow starts
2. GitHub issues JWT to the runner
3. Runner presents JWT to Azure AD token endpoint
4. Azure AD validates JWT against federated credential
5. Azure AD returns access token scoped to the app registration
6. App uses token to call Microsoft Graph / Azure ARM
```

No client secrets. No certificates. Nothing to rotate.

## Scaling

| Tenants | Control Tower | Domain Intel | User Lifecycle |
|---|---|---|---|
| 1–5 | Single App Service (B1) | Single App Service (B1) | GitHub Actions free |
| 5–20 | App Service (P1v2) + Elastic Pool | App Service (P1v2) | GitHub Actions Team |
| 20–100 | App Service (P2v2) + Read replicas | Container Apps | Self-hosted runners |

## Security Model

### Threats Mitigated

| Threat | Mitigation |
|---|---|
| Credential leakage | No secrets in code or CI (OIDC only) |
| Cross-tenant data leakage | Row-level `tenant_id` + middleware enforcement |
| Privilege escalation | RBAC with least privilege, PIM for admin roles |
| Insider threat | Audit logging on every action, immutable logs |
| Configuration drift | All config in Git, all changes via PR |

### Compliance

- SOC 2 Type II ready (audit logs, access controls, change management)
- GDPR ready (data subject export/deletion via User Lifecycle)
- ISO 27001 aligned (access control, cryptography, operations security)