Repository Public
1<!--2SP Notes (macOS)3File: docs/ARCHITECTURE.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Architecture89```10┌──────────────────────────── SP Notes.app (SwiftUI + AppKit) ────────────────────────────┐11│ Features/… vues SwiftUI App/ AppEnvironment · WindowModel · SyncMonitor │12│ NoteSession (une par note ouverte) ── EditorController ── NoteTextView (TextKit 2) │13└───────────────┬───────────────────────────────┬─────────────────────────────────────────┘14 │ SPNotesEditor (ce dépôt) │ SPNotesCore (../SPNotesCore, partagé avec iOS)15 │ codec · styliseur · fragments │ SPNotesDocument · SPNotesStore · SPNotesAPI · SPNotesSync16 ▼ ▼17 NSTextStorage SQLite (WAL, FTS5) ⇄ https://note.spboucher.ai18```1920## 1. Éditeur natif (`Editor/`, paquet `SPNotesEditor`)2122Le serveur stocke une note en **JSON ProseMirror**. Le module partagé `SPNotesDocument` l'aplatit en **lignes** : un bloc de23texte ou un bloc atomique, avec la chaîne de ses conteneurs (liste, élément, citation, encadré…). L'éditeur travaille sur un24`NSTextStorage` qui porte cette structure :2526| Dans le stockage texte | Signification |27|---|---|28| attribut `sp.para` (`ParaStyle`, même objet sur tout le paragraphe) | la ligne sans son contenu : type, attributs, conteneurs. Les lignes d'un bloc de code partagent un même objet. |29| attribut `sp.marks` (`MarkSet`) | les marques brutes du passage (y compris celles que l'app ne connaît pas) |30| caractère de pièce jointe + `AtomAttachment` | un nœud édité d'un bloc : tableau, image, équation, fichier, mention, nœud inconnu |31| `\n` final de chaque paragraphe, y compris le dernier | porte les attributs du paragraphe : un paragraphe vide a un style et dessine sa puce |3233- **`DocumentCodec`** convertit dans les deux sens, sans perte (test : tous les types du schéma web, puis édition + annulation).34- **`Styler`** dérive polices, couleurs, retraits et décorations **pour les seuls paragraphes touchés** (élargis à la liste ou au35 bloc de code qui les contient). Jamais de reconstruction du document à la frappe : 3 ms par touche dans un document de 4 000 blocs.36- **`BlockLayoutFragment`** (`NSTextLayoutFragment`) dessine puces, numéros, cases à cocher, barres de citation, panneaux de code37 et d'encadré. Ces décorations ne sont pas des caractères : elles ne polluent ni la sélection ni le presse-papiers.38- **`NoteTextView`** (`NSTextView` sur TextKit 2) : Entrée, Tab, Retour arrière structurés ; raccourcis Markdown ; menu « / » et39 « @ » ; primitive `replace(_:with:)` par laquelle passe toute commande (une étape d'annulation, historique propre à la note).40- **`applyRemote`** applique un document venu d'ailleurs en ne remplaçant que les lignes qui diffèrent : le curseur ne bouge pas41 quand le changement est ailleurs, et les conteneurs voisins sont réalignés pour qu'une liste ne soit pas coupée.42- Identifiants de blocs : générés à la création (même alphabet que le site), donc stables d'un enregistrement à l'autre et43 identiques à ce que le serveur attend.4445## 2. Persistance (`SPNotesStore`)4647Un fichier SQLite par serveur dans le conteneur de l'application (`Application Support/SPNotes/notes-<hôte>.sqlite`), mode WAL,48`synchronous=FULL` : une écriture confirmée survit à une coupure de courant. Chaque page garde son contenu, sa **copie de base**49(dernier état commun avec le serveur, pour la fusion), ses champs modifiés, et l'index plein texte FTS5 est mis à jour dans la50même transaction. Les pièces jointes sont des fichiers à côté (`files-<hôte>/<id>.<ext>`), référencés par chemin relatif.5152`NoteSession` enregistre 350 ms après la dernière frappe, à la perte de focus de l'application, à la fermeture, et avant de53quitter (`applicationShouldTerminate` attend l'écriture et un point de contrôle). Un instantané d'historique local est pris54avant une salve de modifications (au plus toutes les dix minutes) et à chaque ⌘S.5556## 3. Synchronisation (`SPNotesSync` + `App/SyncMonitor`)5758Le serveur numérote chaque écriture (`rev`, migration 0002, voir `AUDIT.md` §7). Un cycle :59601. créations (parents d'abord, identifiant choisi par le client, clé d'idempotence) ;612. envoi des fichiers joints ;623. métadonnées, tags, puis contenu avec `baseVersion` ;634. file d'actions (corbeille, restauration, suppression définitive) ;645. lecture de `/api/sync?since=<curseur>` jusqu'à épuisement ; application atomique, **jamais par-dessus un contenu local modifié** ;656. téléchargement des images.6667L'application déclenche un cycle au lancement, 2 s après une modification locale, au retour du réseau, au retour au premier68plan et toutes les 75 s quand elle est active.6970### Conflits7172| Situation | Résultat |73|---|---|74| Le serveur a la même chose que ce Mac | adopté, rien à faire |75| Deux appareils ont modifié des blocs **différents** | fusion à trois voies (base / local / serveur), renvoyée au serveur |76| Même bloc modifié des deux côtés, ou modification contre suppression | **conflit enregistré** : la copie locale reste intacte, la copie du serveur est gardée à côté ; bandeau dans la note, comparaison côte à côte, trois issues (la mienne / celle du serveur / les deux). Le serveur conserve les deux dans son historique quel que soit le choix. |77| Frappe non encore enregistrée au moment où un changement distant arrive | même fusion dans `NoteSession` ; si elle est impossible, la copie distante est versée dans l'historique local avant d'être remplacée, et un bandeau le dit |78| Suppression définitive ailleurs d'une note ouverte ici | la note passe en lecture seule avec « Enregistrer comme nouvelle note » |7980Il n'y a nulle part de « dernier qui écrit gagne » silencieux.8182## 4. Fenêtres8384`WindowGroup` principal (plusieurs fenêtres) et un groupe « une fenêtre par note ». Les fenêtres partagent `AppEnvironment` ;85chacune a son `WindowModel` (sélection, panneaux). Deux fenêtres sur la même note partagent la même `NoteSession`, donc le même86texte et le même historique d'annulation. La vue AppKit de l'éditeur appartient à la session : SwiftUI l'héberge sans jamais la87reconstruire.8889## 5. Ce que l'application ne fait pas9091Voir `FEATURE_MATRIX.md` (lignes « — ») : bases de données, graphe, agents, recherche sémantique, tâches, poignée de92glisser-déposer par bloc, mise à jour automatique.9394## 6. SP Notes 2.0 (branche `next`)9596- **Ouverture de la base** : `AppEnvironment` appelle `NotesStore.open` (résultat typé). En cas d'échec `storeFailure` est97 renseigné, `MainWindow.root(for:)` ne rend que `StoreFailureView`, `start()` ne démarre rien et chaque point d'entrée qui98 écrit (`LibraryModel.newNote`, `session(for:)`, capture, Services, import) refuse. La copie d'avant migration est gardée99 30 jours (`AppEnvironment.backupRetention`).100- **Navigation** (`App/Navigation.swift`) : `Destination` (notes + écrans), `Route(pageId, blockId?)`, `DeepLink`.101 `WindowModel` porte la destination, la route en attente et **sa propre** `LibraryModel` (sélection, recherche, liste) ;102 `env.library` reste le modèle partagé qui prévient les sessions ouvertes.103- **Couche d'accueil des écrans** : protocole `FeatureHosting` (`isAvailable`, `screen(for:)`, `badge`). `NativeFeatureHost`104 fournit Tâches, Boîte de réception et Recherche sur `NotesRepositories` ; les autres destinations ne sont pas disponibles105 et ne sont donc listées nulle part. Remplacer `env.features` suffit pour brancher SPNotesFeatures.106- **Blocs** : `Editor/AtomCards.swift` (modèle `AtomCardModel` + dessin), `Editor/ChartDrawing.swift`,107 `Editor/NextCommands.swift`. Côté application, `BlockDetailProviding` (`NativeBlockDetails`) fournit les feuilles ;108 `EditorInsertions` est l'unique liste de ce qui s'insère ; `EditorLookup` répond aux cartes depuis la base locale sans109 bloquer le dessin.110- **Design** : `SPNotesDesign` (jetons) dans l'application, `Editor/EditorTokens.swift` pour AppKit. Les animations passent par111 `NVMotion` / `withNVAnimation` ; l'ouverture d'une note est `NoteTextView.playReveal` (`revealPlan` est testable).112- **Plateforme** : `Features/Platform/` — `PlatformServices` (Spotlight, rappels, derrière deux protocoles pour les tests),113 `QuickNote.swift` (capture). `CommandRegistry` alimente le centre de commandes.114115## 7. SPNotesFeatures dans l'application (2026-11-19, soir)116117- `Features/Hosting/FeaturesHost.swift` : `WindowModel` est le `FeatureRouter` des écrans (`openPage`, `openDatabase`,118 `openCanvas`, `openURL`, `presentError`) ; `FeaturesHost` associe chaque `Destination` à un écran de la bibliothèque (ou aux119 écrans Tâches / Boîte / Recherche de l'app) et ne la déclare disponible que si le serveur annonce la fonction120 (`AppEnvironment.serverMeta`, lu après chaque synchronisation et mémorisé par Core).121- `Features/Hosting/FeatureBlockDetails.swift` : `FeaturesBlockDetails` (le `BlockDetailProviding` actif) enveloppe les vues de122 blocs de la bibliothèque dans `FeatureBlockSheet` ; la vue rend un bloc modifié, l'app écrit le nœud. `AppEnvironment.123 attachmentLoader(pageId:)` lit les fichiers sur le Mac et **range les nouveaux fichiers localement** (dessin, enregistrement) :124 l'envoi est fait par la synchronisation, donc ces blocs s'éditent hors ligne.125- `Features/Hosting/CommandCenterHost.swift` : un seul registre (`CommandRegistry` de la bibliothèque, dans `FeatureServices`) ;126 `AppCommandCatalog` y enregistre les commandes de la fenêtre au premier plan à chaque ouverture.127- `Features/Hosting/NotePages.swift` : pages base / canvas natives, zoom sémantique, chronologie d'une note, choix du modèle.128- Les produits Debug sont construits hors de `~/Desktop` (`~/Library/Developer/SPNotes/DerivedData`) : un hôte de test en bac à129 sable qui charge un framework de paquet depuis le Bureau reste bloqué sur une décision de confidentialité.130