Architecture
SP Chat est un client macOS natif (Swift 6, SwiftUI + AppKit) du backend chat.spboucher.ai. Aucun moteur web n'est
embarqué : ni WKWebView, ni JavaScriptCore (vérifié par Scripts/verify-release.sh sur le binaire).
SPChat/
├── App/ entrée (@main), scènes, commandes de menu, AppDelegate (liens, raccourci global, notifications),
│ AppEnvironment (injection de dépendances), WindowModel (navigation par fenêtre)
├── Core/ paquet SwiftPM « SPChatCore » — aucun import d'interface, testable avec `swift test`
│ ├── Models/ DTO du serveur (décodage tolérant : colonnes numériques en chaînes, champs inconnus conservés)
│ ├── Networking/ HTTPTransport (URLSession éphémère), APIClient (cookie → trousseau, Origin, erreurs, ré-auth), Endpoints typés
│ ├── Authentication/ AuthService : cérémonies WebAuthn (options → authentificateur → vérification), sessions, passkeys
│ ├── Streaming/ SSEParser (octets → événements), ChatEvent, MessageAccumulator, GenerationEngine (tour complet + reprise)
│ ├── Persistence/ CacheStore (SQLite + FTS5) : listes, fils complets, catalogues, recherche hors ligne
│ ├── Security/ SecretStore (trousseau), FileValidator (type sur octets réels), Redactor (journaux sans secrets)
│ ├── Markdown/ MarkdownParser (blocs, math protégée, découpage incrémental), SyntaxHighlighter
│ └── Export/ export Markdown / JSON local
├── Features/ Account · Conversations · Chat · ModelSelector · Attachments · Search · Settings · Workspace
├── Components/ DesignSystem, SidebarView, MessageView, ComposerView, MarkdownView, MathView
├── Resources/ Info.plist, entitlements (Release / Debug), Assets.xcassets, icon/ (sources SVG)
├── Tests/ CoreTests (Swift Testing), AppTests (XCTest hébergé), UITests (XCUITest)
└── Build/ profil de provisionnement Developer IDAjouts de la 2.0 « Next Generation »
- Cœur :
Models/ModelQuery.swift(filtres, tri, index de recherche du catalogue),Models/ProviderModels.swift(fournisseurs, clés, fiche de modèle, suggestion de route),Models/PanelModels.swift(contexte, chronologie, arbre, lentilles),Models/ArenaModels.swift,Models/ConstellationModels.swift,Graph/ForceLayout.swift,Streaming/Lens.swift,Streaming/ReplayCursor.swift,Sync/(fluxGET /api/events, tirageGET /api/sync, réducteur purSyncInvalidation),Models/PromptTemplate.swift(variables, déclencheurs/et@). - Système visuel V2 :
Components/DesignSystem.swift(jetonsDS.*, couleurs dansAssets.xcassets/Tokensgénérées parScripts/sync-design-tokens.py),Components/ModelIdentity.swift(ModelMark,ModelChip,RouteBadge,LumenLine, registre de logos). Les logos (Assets.xcassets/Logos,Resources/LogoRegistry.json) sont générés parScripts/sync-logos.pydepuis le registre canonique partagé avec le web et iOS ; rien n'est chargé à l'exécution. - Catalogue :
CatalogStorechargeroutes=all(cachemodels.v2), expose favoris, récents, dock, index de recherche ; les identifiantsor:<slug>circulent partout où un modèle est nommé. - Synchronisation :
Features/Sync/SyncCoordinatorouvre le flux après la connexion, fusionne les changements par rafales de 350 ms et fait relire aux stores ce qui a changé (le serveur fait foi) ;catchUp()à l'activation ;DraftOutboxgarde les brouillons qui n'ont pas pu être enregistrés et les pousse au retour du réseau. - Écrans :
Features/Chat/Panels/(panneau contextuel à quatre onglets),Features/Workspace/(Explorateur, fiche, comparaison, Arena, Cost Intelligence, Constellation),Features/Settings/ProvidersSettings.swift.
Flux d'un tour de conversation
ComposerView ──send()──▶ ChatViewModel ──start(.send, payload)──▶ GenerationEngine
│ POST /api/chat (clé d'idempotence, 4 essais)
▼
live (≤ 30 Hz) ◀── MessageAccumulator ◀── ChatEvent ◀── SSEParser ◀── URLSessionTransport.stream
│ coupure / silence 45 s
└─▶ GET /api/chat/stream?run=…&after=<dernier index>
fin ─▶ GET /api/conversations/:id?all=1 ─▶ CacheStore.saveDetail ─▶ liste latérale- 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 de coupure le client se rattache avec l'index du dernier événement vu ; si le run n'existe plus, il recharge la conversation, dont les lignes font foi.
ChatViewModel.messages(messages stabilisés) etChatViewModel.live(réponse en cours) sont séparés : le streaming n'invalide jamais les lignes déjà affichées.MessageRowetChunkViewsontEquatable; le Markdown est découpé en blocs indépendants mis en cache, donc seul le dernier bloc est recalculé pendant le flux.
Injection et isolation
AppEnvironmentconstruit tout une fois (serveur,APIClient,AuthService,CacheStore,GenerationEngine, stores observables) et se transmet par l'environnement SwiftUI. Les tests injectent unHTTPTransportscripté et un authentificateur WebAuthn logiciel : aucun singleton réseau.- Cible d'application : isolation
MainActorpar défaut, concurrence stricte Swift 6. Le cœur estSendable(acteur pour SQLite, verrous pour le pot de cookies). - Un
ChatViewModelpar conversation, partagé par toutes les fenêtres ; unWindowModelpar fenêtre.
Extensibilité des fournisseurs
L'app ne parle à aucun fournisseur d'IA directement et ne détient aucune clé : elle consomme le registre du serveur
(/api/models), qui n'expose que les modèles vérifiés par le banc d'essai. Ajouter OpenAI-compatible, un modèle
local ou un service privé se fait donc côté serveur (un adaptateur src/lib/ai/*.ts + une entrée de registre) ; l'app
l'affiche sans mise à jour (Provider.label, couleur par défaut). Un nouveau backend (autre serveur) n'exigerait
qu'une autre implémentation de HTTPTransport/ServerConfiguration.
Dépendances
| Paquet | Version | Usage | Pourquoi |
|---|---|---|---|
| swiftlang/swift-markdown | 0.7.3 (épinglée) | Analyse CommonMark/GFM | Analyseur d'Apple (cmark-gfm), robuste sur les entrées hostiles |
| mgriebling/SwiftMath | 1.7.3 (épinglée) | Composition LaTeX (CoreText) | Rendu mathématique sans moteur web |
| SQLite, Security, CryptoKit (tests), AuthenticationServices, Network, AVFoundation, Charts, QuickLook, UserNotifications, Carbon (raccourci global) | système |
Modifications du backend (dépôt chat-spboucher-ai, commit 52ec509)
GET /.well-known/apple-app-site-association(public, liste3YM54G49SN.ai.spboucher.spchat, surchargeable parAPPLE_APP_IDS).- Libellé d'appareil « Mac · SP Chat » pour l'agent utilisateur de l'app. Aucune route existante n'a été modifiée ; le site web fonctionne à l'identique.