Architektura

Małe monorepo: jeden współdzielony pakiet Swift z modelem danych i dwie cienkie natywne aplikacje (macOS i iOS) zbudowane na nim. Czysty Swift — SwiftUI + AppKit na Macu, SwiftUI na iOS.

Układ repozytorium

Packages/MemoryKit/   współdzielone modele i reguły: elementy, Tablice, retencja, zapis, interfejsy sync
apps/macos/           aplikacja macOS (monitor, panel, Tablice, przypomnienia, wklejanie)
apps/ios/             aplikacja iOS (lokalna pamięć, gesty, szczegóły, Tablice, przypomnienia)
Resources/Info.plist  Info.plist dla builda macOS
project.yml           konfiguracja XcodeGen → generuje MemoryApp.xcodeproj
build.sh              szybki build macOS przez SwiftPM (bez Xcode)

MemoryKit — współdzielony rdzeń

Packages/MemoryKit to pakiet Swift zawierający model danych wspólny dla obu aplikacji. Celowo zależy wyłącznie od Foundation i CryptoKit — bez AppKit, bez UIKit — dzięki czemu kompiluje się bez zmian na macOS i iOS.

ClipType — enum typów treści: text, link, color, image, file, każdy z nazwą wyświetlaną i nazwą ikony SF Symbols.
ClipItem — jeden zapamiętany element: tożsamość, typ, znaczniki czasu, payload, aplikacja źródłowa, pin, członkostwo w Tablicach, termin przypomnienia i hash. Pełna lista pól w Formacie danych.
MemoryBoard i MemoryArchive — nazwane kolekcje oraz jeden atomowy snapshot elementów i Tablic. Pinned, Loved i Saved mają stałe identyfikatory systemowe.
RetentionPolicy, ClipProtection i HistoryRules — czyszczenie po 30/60/90/120 dniach albo bez limitu, z ochroną pinów, Tablic i niewyczyszczonych przypomnień.
HistoryEnvelope i HistoryPersistence — wersjonowane zapisy atomowe, zgodne snapshoty backupu, migracja i odzyskiwanie uszkodzonych plików.
ClipItem.detectTextType(_:) — klasyfikacja skopiowanego tekstu na color / link / text.
Hashing — pomocnicze funkcje SHA-256 używane do deduplikacji po treści.

Aplikacja macOS (`apps/macos`)

Komponent	Odpowiedzialność
`ClipboardMonitor`	Obserwuje `NSPasteboard` przez odpytywanie licznika zmian; klasyfikuje nowe treści, respektuje konwencję poufności `org.nspasteboard` i listę wykluczonych aplikacji.
`HistoryStore`	Właściciel elementów i Tablic: atomowy zapis archiwum, bloby, deduplikacja, retencja czasowa, członkostwo, Loved/Saved, planowanie przypomnień i migracja.
`PanelController`	Wysuwany panel przywoływania. Panel nieaktywujący (wzorzec Spotlight) — aplikacja na wierzchu zachowuje fokus podczas przeglądania.
`HistoryView`	Panel SwiftUI: globalne wyszukiwanie, filtry, siatka kart, szybkie Loved/Saved, menu Tablic i przypomnień, klawiatura, drag & drop i menu kontekstowe.
`LibraryView`	Widok wszystkich Tablic, edytor Tablic, listy elementów i arkusze szczegółów/przypomnień.
`ReminderScheduler`	Prosi o uprawnienie, planuje/anuluje lokalne powiadomienia i kieruje otwarcie do stabilnego ID elementu.
`HotkeyManager`	Rejestruje globalny skrót `⌘⇧V`.
`PasteHelper`	Wkleja do aktywnej aplikacji, syntetyzując `⌘V` (CGEvent); wymaga uprawnienia Dostępność. Wariant czysto-tekstowy dla `⌥↩`.
`SettingsView`	Preferencje: retencja 30/60/90/120 dni lub bez limitu, wykluczone aplikacje, start przy logowaniu.
`ColorHex`	Parsowanie/wyświetlanie kolorów HEX dla podglądów kolorów.
`main.swift`	Rozruch aplikacji: element paska menu (🧠), spięcie monitora, magazynu, panelu i skrótu.

Aplikacja iOS (`apps/ios`)

Aplikacja iOS (bundle id cc.memoryapp.ios) jest natywnym klientem tej samej pamięci co aplikacja na Maca, synchronizowanej przez iCloud w podpisanych buildach. Obsługuje globalne wyszukiwanie, gest lewo-do-Usuniętych/prawo-przypnij, dotknięcie do szczegółów, menu po przytrzymaniu, Loved/Saved, nazwane Tablice, przypomnienia i bezpieczne otwieranie linków.

Komponent	Odpowiedzialność
`MemoryAppApp` / `IOSAppDelegate`	Wejście SwiftUI, konfiguracja kategorii powiadomień i kierowanie odpowiedzi do ID elementu.
`IOSStore`	Lokalny magazyn elementów i Tablic: wyszukiwanie, członkostwo, przypomnienia, retencja, zapis archiwum i interfejs sync (aktywny w podpisanych buildach).
`ContentView`	Lista, wyszukiwanie, szybkie Loved/Saved, gesty, menu po przytrzymaniu i dodawanie ze schowka.
`IOSItemDetailView`	Arkusz szczegółów, bezpieczne linki, członkostwo w Tablicach i edytor przypomnienia.
`IOSBoardsView`	Widok wszystkich Tablic, zarządzanie własnymi Tablicami i listy zawężone do Tablicy.
`IOSReminderScheduler`	Autoryzacja, planowanie, anulowanie i uzgadnianie lokalnych powiadomień.

Przepływ danych (macOS)

kopiowanie w dowolnej aplikacji
      │
      ▼
NSPasteboard ──(odpytywanie)──▶ ClipboardMonitor
                                  │  klasyfikacja (text/link/color/image/file)
                                  │  pomijanie poufnych + wykluczonych aplikacji
                                  ▼
                            HistoryStore ──▶ wersjonowane archiwum + blobs/
                                  │  deduplikacja + Tablice + przypomnienia + retencja
                                  ▼
⌘⇧V ──▶ HotkeyManager ──▶ PanelController ──▶ HistoryView
                                  │
                     klik / ↩ / drag & drop
                                  ▼
                    schowek  ──▶ PasteHelper (⌘V do aktywnej aplikacji)

System budowania

build.sh — szybka ścieżka: buduje aplikację macOS samym SwiftPM. Artefakty trafiają do ~/Library/Caches/MemoryAppBuild, żeby (synchronizowane z chmurą) repo pozostało czyste.
project.yml + XcodeGen — generuje MemoryApp.xcodeproj z celami MemoryApp-macOS i MemoryApp-iOS. Plik projektu jest jednorazowy; źródłem prawdy jest project.yml.

Architektura synchronizacji iCloud

Podpisane buildy z uprawnieniami domyślnie używają CloudKitSyncEngine i zachowują lokalną kopię offline. Elementy, stan Usunięte i definicje Tablic trafiają do prywatnej bazy CloudKit użytkownika; SyncPocket App nie prowadzi serwera danych i nie może czytać archiwum. Każdy element ma modifiedAt: wygrywa nowsza zmiana, przy identycznym czasie wygrywa stan Usunięte, a konflikt zapisu jest ponawiany z najnowszym znacznikiem zmiany serwera. Izolowane testy UI używają NoopSyncEngine. Wydanie nadal wymaga podpisanego kontenera produkcyjnego i testu konfliktów na dwóch urządzeniach.