Repository Public
1<!--2Author: Simon-Pierre Boucher — contact@spboucher.ai3File: docs/ARCHITECTURE.md4-->5# Architecture67```8SwiftUI (App, Features, Components) ── AppModel ──┐9 ▼10 PlaybackController ── AudioEngine ── AVAudioEngine ── sortie Core Audio11 │ ▲12 │ ResolvedSource │ ByteSource : LocalFileSource | ProgressiveHTTPSource (+ FLACSliceSource)13 ▼ │14 LibrarySession ───────────┘15 ├─ LibraryStore (SQLite, FTS5) tout ce que l'interface affiche, sans réseau16 ├─ StorageManager + PathGuard fichiers sur disque, seules suppressions autorisées17 ├─ DownloadManager file persistante, reprise par plage, SHA-25618 ├─ SyncEngine opérations locales → cluster, deltas cluster → local19 ├─ ArtworkStore pochettes sur disque20 └─ APIClient + Connectivity JSON, session, état du réseau21```2223## Règles tenues2425- **Le moteur audio ne connaît ni les titres ni le réseau** : il reçoit des sources d'octets et des jetons.26- **Le moteur de téléchargement ne connaît pas le moteur audio** ; il réutilise seulement un fichier complet du cache de lecture.27- **La bibliothèque locale n'a jamais besoin du serveur** : ouvrir une session, lister, chercher et lire un titre téléchargé ne font aucune requête (prouvé par un test qui compte les connexions).28- **Rien n'est supprimé hors d'un dossier marqué par l'app**, liens symboliques résolus.2930## Lecture3132- Deux platines (lecteur → mélangeur) alimentent un pré-mélangeur, l'égaliseur, puis le mélangeur principal. La piste33 suivante est préparée sur l'autre platine et démarrée à l'échantillon exact où la courante se termine (pas de blanc),34 ou plus tôt avec une rampe à puissance constante (fondu).35- Chaque platine décode sur sa propre file : une source qui attend le réseau ne bloque jamais les commandes.36- Les rappels du lecteur AVFoundation ne prennent jamais le verrou du moteur sur un fil audio (cause de deux interblocages37 trouvés par les tests).38- **Lecture en continu** : `ProgressiveHTTPSource` écrit dans un fichier creux par requêtes de plage ; le décodeur lit ce39 qui est arrivé. Un saut demande les octets de la destination. Fichier complet → vérifié par SHA-256 → marqué, réutilisable.40- **FLAC** : Core Audio se déplace dans un FLAC en le relisant depuis le début (mesuré, avec ou sans table de recherche).41 `FLACIndex` trouve une frontière de trame juste avant la cible (SEEKTABLE, sinon synchro de trame validée par CRC-8 et42 par la trame suivante) et `FLACSliceSource` présente « en-tête + audio à partir de là » au décodeur. Exact à l'échantillon.43- **Fidélité** : aucun transcodage ; égaliseur, normalisation et fondu désactivables d'un bloc (« mode direct ») ;44 option pour régler la fréquence du périphérique sur celle du titre. L'app n'annonce pas de lecture « bit-perfect ».4546## Synchronisation4748Une passe : (1) envoyer les opérations locales, dans l'ordre ; (2) tirer le catalogue depuis la dernière révision vue49(tout, si demandé, si plus de 24 h, ou si les compteurs divergent) ; (3) tirer listes et favoris du compte, sauf si des50opérations attendent encore ; (4) historique dans les deux sens ; (5) mettre en file les téléchargements des51collections « gardées hors ligne ». Aucun fichier audio n'est transféré par une synchronisation.5253Conflit de liste (modifiée ici hors ligne et ailleurs) : aucune version n'est écrasée ; celle du Mac est enregistrée à54côté sous « … (copie de ce Mac) » et l'utilisateur est prévenu.5556## Téléchargements5758Octets dans `<bibliothèque>/.spmusic/partial/<titre>.<asset>.part` ; reprise par `Range` + `If-Range` sur l'identifiant59de l'asset ; taille puis SHA-256 vérifiés avant un déplacement atomique vers le nom lisible. L'état est en base : une60fermeture ou un plantage ne perd rien. Un fichier remplacé sur le cluster est retéléchargé ; un titre supprimé du cluster61mais téléchargé ici est conservé et signalé.62