Repository Public
1<!--2SP Chat — native macOS3File: docs/ARCHITECTURE.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Architecture89SP Chat est un client macOS natif (Swift 6, SwiftUI + AppKit) du backend `chat.spboucher.ai`. Aucun moteur web n'est10embarqué : ni WKWebView, ni JavaScriptCore (vérifié par `Scripts/verify-release.sh` sur le binaire).1112```13SPChat/14├── App/ entrée (@main), scènes, commandes de menu, AppDelegate (liens, raccourci global, notifications),15│ AppEnvironment (injection de dépendances), WindowModel (navigation par fenêtre)16├── Core/ paquet SwiftPM « SPChatCore » — aucun import d'interface, testable avec `swift test`17│ ├── Models/ DTO du serveur (décodage tolérant : colonnes numériques en chaînes, champs inconnus conservés)18│ ├── Networking/ HTTPTransport (URLSession éphémère), APIClient (cookie → trousseau, Origin, erreurs, ré-auth), Endpoints typés19│ ├── Authentication/ AuthService : cérémonies WebAuthn (options → authentificateur → vérification), sessions, passkeys20│ ├── Streaming/ SSEParser (octets → événements), ChatEvent, MessageAccumulator, GenerationEngine (tour complet + reprise)21│ ├── Persistence/ CacheStore (SQLite + FTS5) : listes, fils complets, catalogues, recherche hors ligne22│ ├── Security/ SecretStore (trousseau), FileValidator (type sur octets réels), Redactor (journaux sans secrets)23│ ├── Markdown/ MarkdownParser (blocs, math protégée, découpage incrémental), SyntaxHighlighter24│ └── Export/ export Markdown / JSON local25├── Features/ Account · Conversations · Chat · ModelSelector · Attachments · Search · Settings · Workspace26├── Components/ DesignSystem, SidebarView, MessageView, ComposerView, MarkdownView, MathView27├── Resources/ Info.plist, entitlements (Release / Debug), Assets.xcassets, icon/ (sources SVG)28├── Tests/ CoreTests (Swift Testing), AppTests (XCTest hébergé), UITests (XCUITest)29└── Build/ profil de provisionnement Developer ID30```3132## Ajouts de la 2.0 « Next Generation »3334- **Cœur** : `Models/ModelQuery.swift` (filtres, tri, index de recherche du catalogue), `Models/ProviderModels.swift`35 (fournisseurs, clés, fiche de modèle, suggestion de route), `Models/PanelModels.swift` (contexte, chronologie, arbre,36 lentilles), `Models/ArenaModels.swift`, `Models/ConstellationModels.swift`, `Graph/ForceLayout.swift`,37 `Streaming/Lens.swift`, `Streaming/ReplayCursor.swift`, `Sync/` (flux `GET /api/events`, tirage `GET /api/sync`,38 réducteur pur `SyncInvalidation`), `Models/PromptTemplate.swift` (variables, déclencheurs `/` et `@`).39- **Système visuel V2** : `Components/DesignSystem.swift` (jetons `DS.*`, couleurs dans `Assets.xcassets/Tokens` générées40 par `Scripts/sync-design-tokens.py`), `Components/ModelIdentity.swift` (`ModelMark`, `ModelChip`, `RouteBadge`,41 `LumenLine`, registre de logos). Les logos (`Assets.xcassets/Logos`, `Resources/LogoRegistry.json`) sont générés par42 `Scripts/sync-logos.py` depuis le registre canonique partagé avec le web et iOS ; rien n'est chargé à l'exécution.43- **Catalogue** : `CatalogStore` charge `routes=all` (cache `models.v2`), expose favoris, récents, dock, index de44 recherche ; les identifiants `or:<slug>` circulent partout où un modèle est nommé.45- **Synchronisation** : `Features/Sync/SyncCoordinator` ouvre le flux après la connexion, fusionne les changements par46 rafales de 350 ms et fait relire aux stores ce qui a changé (le serveur fait foi) ; `catchUp()` à l'activation ;47 `DraftOutbox` garde les brouillons qui n'ont pas pu être enregistrés et les pousse au retour du réseau.48- **Écrans** : `Features/Chat/Panels/` (panneau contextuel à quatre onglets), `Features/Workspace/` (Explorateur, fiche,49 comparaison, Arena, Cost Intelligence, Constellation), `Features/Settings/ProvidersSettings.swift`.5051## Flux d'un tour de conversation5253```54ComposerView ──send()──▶ ChatViewModel ──start(.send, payload)──▶ GenerationEngine55 │ POST /api/chat (clé d'idempotence, 4 essais)56 ▼57 live (≤ 30 Hz) ◀── MessageAccumulator ◀── ChatEvent ◀── SSEParser ◀── URLSessionTransport.stream58 │ coupure / silence 45 s59 └─▶ GET /api/chat/stream?run=…&after=<dernier index>60fin ─▶ GET /api/conversations/:id?all=1 ─▶ CacheStore.saveDetail ─▶ liste latérale61```6263- Le serveur exécute chaque génération **détachée** de la connexion. Le flux SSE n'est qu'une *vue* du run : en cas de64 coupure le client se rattache avec l'index du dernier événement vu ; si le run n'existe plus, il recharge la65 conversation, dont les lignes font foi.66- `ChatViewModel.messages` (messages stabilisés) et `ChatViewModel.live` (réponse en cours) sont séparés : le streaming67 n'invalide jamais les lignes déjà affichées. `MessageRow` et `ChunkView` sont `Equatable` ; le Markdown est découpé en68 blocs indépendants mis en cache, donc seul le dernier bloc est recalculé pendant le flux.6970## Injection et isolation7172- `AppEnvironment` construit tout une fois (serveur, `APIClient`, `AuthService`, `CacheStore`, `GenerationEngine`, stores73 observables) et se transmet par l'environnement SwiftUI. Les tests injectent un `HTTPTransport` scripté et un74 authentificateur WebAuthn logiciel : aucun singleton réseau.75- Cible d'application : isolation `MainActor` par défaut, concurrence stricte Swift 6. Le cœur est `Sendable` (acteur76 pour SQLite, verrous pour le pot de cookies).77- Un `ChatViewModel` par conversation, partagé par toutes les fenêtres ; un `WindowModel` par fenêtre.7879## Extensibilité des fournisseurs8081L'app ne parle à aucun fournisseur d'IA directement et ne détient aucune clé : elle consomme le registre du serveur82(`/api/models`), qui n'expose que les modèles **vérifiés par le banc d'essai**. Ajouter OpenAI-compatible, un modèle83local ou un service privé se fait donc côté serveur (un adaptateur `src/lib/ai/*.ts` + une entrée de registre) ; l'app84l'affiche sans mise à jour (`Provider.label`, couleur par défaut). Un nouveau *backend* (autre serveur) n'exigerait85qu'une autre implémentation de `HTTPTransport`/`ServerConfiguration`.8687## Dépendances8889| Paquet | Version | Usage | Pourquoi |90|---|---|---|---|91| swiftlang/swift-markdown | 0.7.3 (épinglée) | Analyse CommonMark/GFM | Analyseur d'Apple (cmark-gfm), robuste sur les entrées hostiles |92| mgriebling/SwiftMath | 1.7.3 (épinglée) | Composition LaTeX (CoreText) | Rendu mathématique sans moteur web |93| SQLite, Security, CryptoKit (tests), AuthenticationServices, Network, AVFoundation, Charts, QuickLook, UserNotifications, Carbon (raccourci global) | système | | |9495## Modifications du backend (dépôt `chat-spboucher-ai`, commit `52ec509`)9697- `GET /.well-known/apple-app-site-association` (public, liste `3YM54G49SN.ai.spboucher.spchat`, surchargeable par `APPLE_APP_IDS`).98- Libellé d'appareil « Mac · SP Chat » pour l'agent utilisateur de l'app.99Aucune route existante n'a été modifiée ; le site web fonctionne à l'identique.100