SPB Git

Repository Public

ARCHITECTURE.md 10.2 KB

# Architecture

text
┌──────────────────────────── SP Notes.app (SwiftUI + AppKit) ────────────────────────────┐
│  Features/…  vues SwiftUI          App/  AppEnvironment · WindowModel · SyncMonitor       │
│  NoteSession (une par note ouverte) ── EditorController ── NoteTextView (TextKit 2)       │
└───────────────┬───────────────────────────────┬─────────────────────────────────────────┘
                │ SPNotesEditor (ce dépôt)      │ SPNotesCore (../SPNotesCore, partagé avec iOS)
                │  codec · styliseur · fragments │  SPNotesDocument · SPNotesStore · SPNotesAPI · SPNotesSync
                ▼                                ▼
        NSTextStorage                     SQLite (WAL, FTS5)  ⇄  https://note.spboucher.ai

# 1. Éditeur natif (Editor/, paquet SPNotesEditor)

Le serveur stocke une note en JSON ProseMirror. Le module partagé SPNotesDocument l'aplatit en lignes : un bloc de texte ou un bloc atomique, avec la chaîne de ses conteneurs (liste, élément, citation, encadré…). L'éditeur travaille sur un NSTextStorage qui porte cette structure :

Dans le stockage texte Signification
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.
attribut sp.marks (MarkSet) les marques brutes du passage (y compris celles que l'app ne connaît pas)
caractère de pièce jointe + AtomAttachment un nœud édité d'un bloc : tableau, image, équation, fichier, mention, nœud inconnu
\n final de chaque paragraphe, y compris le dernier porte les attributs du paragraphe : un paragraphe vide a un style et dessine sa puce
  • DocumentCodec convertit dans les deux sens, sans perte (test : tous les types du schéma web, puis édition + annulation).
  • Styler dérive polices, couleurs, retraits et décorations pour les seuls paragraphes touchés (élargis à la liste ou au bloc de code qui les contient). Jamais de reconstruction du document à la frappe : 3 ms par touche dans un document de 4 000 blocs.
  • BlockLayoutFragment (NSTextLayoutFragment) dessine puces, numéros, cases à cocher, barres de citation, panneaux de code et d'encadré. Ces décorations ne sont pas des caractères : elles ne polluent ni la sélection ni le presse-papiers.
  • NoteTextView (NSTextView sur TextKit 2) : Entrée, Tab, Retour arrière structurés ; raccourcis Markdown ; menu « / » et « @ » ; primitive replace(_:with:) par laquelle passe toute commande (une étape d'annulation, historique propre à la note).
  • applyRemote applique un document venu d'ailleurs en ne remplaçant que les lignes qui diffèrent : le curseur ne bouge pas quand le changement est ailleurs, et les conteneurs voisins sont réalignés pour qu'une liste ne soit pas coupée.
  • Identifiants de blocs : générés à la création (même alphabet que le site), donc stables d'un enregistrement à l'autre et identiques à ce que le serveur attend.

# 2. Persistance (SPNotesStore)

Un fichier SQLite par serveur dans le conteneur de l'application (Application Support/SPNotes/notes-<hôte>.sqlite), mode WAL, synchronous=FULL : une écriture confirmée survit à une coupure de courant. Chaque page garde son contenu, sa copie de base (dernier état commun avec le serveur, pour la fusion), ses champs modifiés, et l'index plein texte FTS5 est mis à jour dans la même transaction. Les pièces jointes sont des fichiers à côté (files-<hôte>/<id>.<ext>), référencés par chemin relatif.

NoteSession enregistre 350 ms après la dernière frappe, à la perte de focus de l'application, à la fermeture, et avant de quitter (applicationShouldTerminate attend l'écriture et un point de contrôle). Un instantané d'historique local est pris avant une salve de modifications (au plus toutes les dix minutes) et à chaque ⌘S.

# 3. Synchronisation (SPNotesSync + App/SyncMonitor)

Le serveur numérote chaque écriture (rev, migration 0002, voir AUDIT.md §7). Un cycle :

  1. créations (parents d'abord, identifiant choisi par le client, clé d'idempotence) ;
  2. envoi des fichiers joints ;
  3. métadonnées, tags, puis contenu avec baseVersion ;
  4. file d'actions (corbeille, restauration, suppression définitive) ;
  5. lecture de /api/sync?since=<curseur> jusqu'à épuisement ; application atomique, jamais par-dessus un contenu local modifié ;
  6. téléchargement des images.

L'application déclenche un cycle au lancement, 2 s après une modification locale, au retour du réseau, au retour au premier plan et toutes les 75 s quand elle est active.

# Conflits

Situation Résultat
Le serveur a la même chose que ce Mac adopté, rien à faire
Deux appareils ont modifié des blocs différents fusion à trois voies (base / local / serveur), renvoyée au serveur
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.
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
Suppression définitive ailleurs d'une note ouverte ici la note passe en lecture seule avec « Enregistrer comme nouvelle note »

Il n'y a nulle part de « dernier qui écrit gagne » silencieux.

# 4. Fenêtres

WindowGroup principal (plusieurs fenêtres) et un groupe « une fenêtre par note ». Les fenêtres partagent AppEnvironment ; chacune a son WindowModel (sélection, panneaux). Deux fenêtres sur la même note partagent la même NoteSession, donc le même texte et le même historique d'annulation. La vue AppKit de l'éditeur appartient à la session : SwiftUI l'héberge sans jamais la reconstruire.

# 5. Ce que l'application ne fait pas

Voir FEATURE_MATRIX.md (lignes « — ») : bases de données, graphe, agents, recherche sémantique, tâches, poignée de glisser-déposer par bloc, mise à jour automatique.

# 6. SP Notes 2.0 (branche next)

  • Ouverture de la base : AppEnvironment appelle NotesStore.open (résultat typé). En cas d'échec storeFailure est renseigné, MainWindow.root(for:) ne rend que StoreFailureView, start() ne démarre rien et chaque point d'entrée qui écrit (LibraryModel.newNote, session(for:), capture, Services, import) refuse. La copie d'avant migration est gardée 30 jours (AppEnvironment.backupRetention).
  • Navigation (App/Navigation.swift) : Destination (notes + écrans), Route(pageId, blockId?), DeepLink. WindowModel porte la destination, la route en attente et sa propre LibraryModel (sélection, recherche, liste) ; env.library reste le modèle partagé qui prévient les sessions ouvertes.
  • Couche d'accueil des écrans : protocole FeatureHosting (isAvailable, screen(for:), badge). NativeFeatureHost fournit Tâches, Boîte de réception et Recherche sur NotesRepositories ; les autres destinations ne sont pas disponibles et ne sont donc listées nulle part. Remplacer env.features suffit pour brancher SPNotesFeatures.
  • Blocs : Editor/AtomCards.swift (modèle AtomCardModel + dessin), Editor/ChartDrawing.swift, Editor/NextCommands.swift. Côté application, BlockDetailProviding (NativeBlockDetails) fournit les feuilles ; EditorInsertions est l'unique liste de ce qui s'insère ; EditorLookup répond aux cartes depuis la base locale sans bloquer le dessin.
  • Design : SPNotesDesign (jetons) dans l'application, Editor/EditorTokens.swift pour AppKit. Les animations passent par NVMotion / withNVAnimation ; l'ouverture d'une note est NoteTextView.playReveal (revealPlan est testable).
  • Plateforme : Features/Platform/ — PlatformServices (Spotlight, rappels, derrière deux protocoles pour les tests), QuickNote.swift (capture). CommandRegistry alimente le centre de commandes.

# 7. SPNotesFeatures dans l'application (2026-11-19, soir)

  • Features/Hosting/FeaturesHost.swift : WindowModel est le FeatureRouter des écrans (openPage, openDatabase, openCanvas, openURL, presentError) ; FeaturesHost associe chaque Destination à un écran de la bibliothèque (ou aux écrans Tâches / Boîte / Recherche de l'app) et ne la déclare disponible que si le serveur annonce la fonction (AppEnvironment.serverMeta, lu après chaque synchronisation et mémorisé par Core).
  • Features/Hosting/FeatureBlockDetails.swift : FeaturesBlockDetails (le BlockDetailProviding actif) enveloppe les vues de blocs de la bibliothèque dans FeatureBlockSheet ; la vue rend un bloc modifié, l'app écrit le nœud. AppEnvironment. attachmentLoader(pageId:) lit les fichiers sur le Mac et range les nouveaux fichiers localement (dessin, enregistrement) : l'envoi est fait par la synchronisation, donc ces blocs s'éditent hors ligne.
  • Features/Hosting/CommandCenterHost.swift : un seul registre (CommandRegistry de la bibliothèque, dans FeatureServices) ; AppCommandCatalog y enregistre les commandes de la fenêtre au premier plan à chaque ouverture.
  • Features/Hosting/NotePages.swift : pages base / canvas natives, zoom sémantique, chronologie d'une note, choix du modèle.
  • Les produits Debug sont construits hors de ~/Desktop (~/Library/Developer/SPNotes/DerivedData) : un hôte de test en bac à sable qui charge un framework de paquet depuis le Bureau reste bloqué sur une décision de confidentialité.
Files main
Menu

Theme