docs: map existing codebase

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,149 @@
+# External Integrations
+
+**Analysis Date:** 2026-04-02
+
+## APIs & External Services
+
+**SharePoint Online:**
+- Service: Microsoft SharePoint Online (via Microsoft 365)
+- What it's used for: Site management, permission auditing, file search, storage metrics, templating, bulk operations
+  - SDK/Client: PnP.PowerShell module
+  - Auth: Azure AD interactive login (ClientId required)
+  - Connection method: `Connect-PnPOnline -Url <SiteUrl> -Interactive -ClientId <ClientId>`
+  - Search: SharePoint Search API using KQL (keyword query language) via `Submit-PnPSearchQuery`
+
+**Azure AD:**
+- Service: Microsoft Entra ID (formerly Azure Active Directory)
+- What it's used for: User authentication and app registration
+  - SDK/Client: PnP.PowerShell (handles auth flow)
+  - Auth: Interactive browser-based login
+  - App Registration: Required with delegated permissions configured
+  - No service principal or client secret used (interactive auth only)
+
+## Data Storage
+
+**Databases:**
+- None detected - Application uses file-based storage only
+
+**File Storage:**
+- Service: Local filesystem only
+- Connection: Configured data folder for JSON files
+- Client: PowerShell native file I/O
+- Configuration: `Sharepoint_Settings.json` stores dataFolder path
+
+**Caching:**
+- Service: None detected
+- In-memory collections used during session (synchronized hashtables for runspace communication)
+
+## Authentication & Identity
+
+**Auth Provider:**
+- Azure AD (Microsoft Entra ID)
+  - Implementation: Interactive browser-based OAuth 2.0 flow
+  - No client secrets or certificates
+  - User must have access to target SharePoint tenant
+  - App registration required with delegated permissions
+
+**Registration Process:**
+- User creates Azure AD App Registration
+- Client ID stored in profile for reuse
+- Helper script available: `Register-PnPEntraIDAppForInteractiveLogin` (via PnP.PowerShell)
+- Result file: Temporary JSON stored in system temp folder, user copies Client ID manually
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- None detected - Errors written to UI log box via `Write-Log` function
+- Location: UI RichTextBox control in application
+
+**Logs:**
+- Approach: In-app console logging
+  - Function: `Write-Log $Message [Color]` writes timestamped messages to UI log box
+  - Colors: LightGreen (default), Red (errors), Yellow (KQL queries), DarkOrange (dry-run operations)
+  - File location: `C:\Users\SebastienQUEROL\Documents\projets\Sharepoint\Sharepoint_ToolBox.ps1` (lines 6-17)
+
+## CI/CD & Deployment
+
+**Hosting:**
+- Not applicable - Desktop application (local execution)
+
+**CI Pipeline:**
+- None detected
+
+**Execution Model:**
+- Direct script execution: `.\Sharepoint_Toolbox.ps1`
+- No installation/setup required beyond PowerShell and PnP.PowerShell module
+
+## Environment Configuration
+
+**Required env vars:**
+- None required - All configuration stored in JSON files
+- User inputs via GUI: Client ID, Tenant URL, Site URL
+
+**Secrets location:**
+- Not applicable - Interactive auth uses no stored secrets
+- User manages Client ID (non-sensitive app identifier)
+- Session credentials handled by Azure AD auth flow (in-memory only)
+
+**Configuration files:**
+- `Sharepoint_Settings.json` - Data folder, language preference
+- `Sharepoint_Export_profiles.json` - Saved connection profiles (Tenant URL, Client ID)
+- `Sharepoint_Templates.json` - Captured site templates
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- None detected
+
+**Outgoing:**
+- None detected
+
+## Search & Query Integration
+
+**SharePoint Search API:**
+- Usage: File search across libraries using KQL
+- Location: `Sharepoint_ToolBox.ps1` lines 4744-4773 (search query building)
+- Function: `Submit-PnPSearchQuery -Query $kql`
+- Pagination: Automatic via PnP.PowerShell
+- Client-side filtering: Regex filters applied after results fetched
+- Query example: Supports file extension, name/path patterns, creation/modification date ranges, author filters, max result limits
+
+## Export & Report Formats
+
+**Output Formats:**
+- CSV: PowerShell `Export-Csv` cmdlet (UTF-8 encoding, no type info)
+- HTML: Custom HTML generation with:
+  - Interactive tables (sorting, filtering by column)
+  - Collapsible sections (durable state via CSS/JS)
+  - Charts and metrics visualization
+  - Inline styling (no external CSS file)
+
+**Export Functions:**
+- `Export-PermissionsToHTML` (line 1389)
+- `Export-StorageToHTML` (line 1621)
+- `Export-SearchResultsToHTML` (line 2112)
+- `Export-DuplicatesToHTML` (line 2235)
+- `Export-TransferVerifyToHTML` (line 2412)
+
+## Bulk Import Formats
+
+**CSV Input:**
+- Bulk member add: Expects columns for site, group, user email
+- Bulk site creation: Site name, alias, owner email, description
+- Bulk file transfer: Source site/path, destination site/path
+- Folder structure: Library name, folder path, permissions
+
+**Parsing:**
+- PowerShell `Import-Csv` - Standard CSV parsing
+- Headers used as property names
+
+## API Rate Limiting
+
+**SharePoint Online:**
+- No explicit rate limiting handling detected
+- Assumes PnP.PowerShell handles throttling internally
+- Pagination used for large result sets (PageSize 2000 for list items)
+
+---
+
+*Integration audit: 2026-04-02*