SPB Git

Repository Public

ARCHITECTURE.md 7.4 KB

# 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).

text
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 ID

# Ajouts 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/ (flux GET /api/events, tirage GET /api/sync, réducteur pur SyncInvalidation), Models/PromptTemplate.swift (variables, déclencheurs / et @).
  • Système visuel V2 : Components/DesignSystem.swift (jetons DS.*, couleurs dans Assets.xcassets/Tokens générées par Scripts/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 par Scripts/sync-logos.py depuis le registre canonique partagé avec le web et iOS ; rien n'est chargé à l'exécution.
  • Catalogue : CatalogStore charge routes=all (cache models.v2), expose favoris, récents, dock, index de recherche ; les identifiants or:<slug> circulent partout où un modèle est nommé.
  • Synchronisation : Features/Sync/SyncCoordinator ouvre 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 ; DraftOutbox garde 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

text
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) et ChatViewModel.live (réponse en cours) sont séparés : le streaming n'invalide jamais les lignes déjà affichées. MessageRow et ChunkView sont Equatable ; 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

  • AppEnvironment construit tout une fois (serveur, APIClient, AuthService, CacheStore, GenerationEngine, stores observables) et se transmet par l'environnement SwiftUI. Les tests injectent un HTTPTransport scripté et un authentificateur WebAuthn logiciel : aucun singleton réseau.
  • Cible d'application : isolation MainActor par défaut, concurrence stricte Swift 6. Le cœur est Sendable (acteur pour SQLite, verrous pour le pot de cookies).
  • Un ChatViewModel par conversation, partagé par toutes les fenêtres ; un WindowModel par 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, liste 3YM54G49SN.ai.spboucher.spchat, surchargeable par APPLE_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.
Files main
Menu

Theme