ShaarIt

ShaarIt est un client Android natif pour Shaarli, le gestionnaire de favoris auto-hébergé. Développé avec les technologies Android modernes, il offre une expérience mobile fluide pour gérer vos liens.

---

📱 Fonctionnalités

🔐 Authentification

• Connexion sécurisée à votre instance Shaarli auto-hébergée (API v1)
• Stockage chiffré des tokens JWT et secrets API via EncryptedSharedPreferences
• Génération automatique de tokens JWT avec algorithme HS512
• Vérification automatique du token au démarrage (skip login si valide)

📚 Gestion des Favoris

• Flux infini : Défilement continu avec chargement progressif (Paging 3)
• Recherche avancée : Recherche locale avec FTS4 (full-text search) et filtrage par tags
• Mode hors-ligne : Consultation et modification des liens même sans connexion
• Ajout rapide : Création de liens privés/publics avec description, tags et extraction automatique de métadonnées
• Notes Markdown : Création de notes enrichies (pas uniquement des URLs) avec le préfixe note://
• Édition : Modification complète des liens existants avec éditeur Markdown
• Suppression : Gestion facile des favoris avec file d'attente de sync
• Détection des doublons : Alerte lors de l'ajout d'un lien existant avec option de mise à jour
• Liens épinglés : Mise en avant des liens importants avec écran dédié
• Vérification santé des liens : Détection automatique des liens morts (Dead Links) en arrière-plan

🏷️ Gestion des Tags

• Vue dédiée pour parcourir tous les tags
• Compteur d'utilisation par tag
• Filtrage rapide du flux par tag
• Tags favoris pour accès rapide

📁 Collections

• Organisation des liens en collections manuelles ou intelligentes
• Collections intelligentes avec filtres automatiques (basées sur les tags)
• Synchronisation des collections via le serveur Shaarli
• Vue grille adaptative pour les collections

📝 Éditeur Markdown

• Édition avec prévisualisation en temps réel
• Mode édition/prévisualisation/split
• Mode lecture focus sans distraction
• Barre d'outils de formatage

Intelligence Artificielle (Google Gemini)

• Analyse IA d'URL : Extraction intelligente du titre, description et tags via Gemini
• Suggestions de tags IA : Génération automatique de tags pertinents
• Classification de contenu : Détection automatique du type (Article, Vidéo, Tutorial, Repository)
• Fallback multi-modèles : Essai automatique de plusieurs modèles Gemini (2.5 Flash Lite → 1.5 Flash)
• Classification en lot : Scan et classification de tous les bookmarks existants

🏷️ Scanner et Classer (Maintenance)

La fonction "Scanner et Classer" disponible dans les paramètres permet d'analyser automatiquement tous vos bookmarks pour améliorer leur organisation :

Fonctionnement automatique

1. Analyse des URLs : Le système examine chaque lien de votre collection

2. Détection du type de contenu : Classification automatique selon 14 catégories :

   • Article : Articles de blog, actualités, publications
   • Vidéo : YouTube, Vimeo, Dailymotion, Twitch, Netflix
   • 🎵 Musique : Spotify (tracks/albums/artists/playlists), Deezer, Tidal, Apple Music, YouTube Music, Bandcamp, SoundCloud, Mixcloud, Beatport
   • 📻 Radio (nouveau) : TuneIn, Radio Garden, myTuner, iHeartRadio, OnlineRadioBox, radio.net, FluxRadios, Radio-Canada OHdio (direct/premiere), flux streaming (.m3u/.m3u8/.pls), serveurs Icecast/Shoutcast
   • 🎙️ Podcast : Apple Podcasts, Overcast, Pocket Casts, Castbox, Stitcher, Acast, Anchor, Libsyn, Simplecast, Buzzsprout, Spotify (shows/épisodes), Radio-Canada OHdio (balados), flux RSS/XML audio
   • Social : Facebook, Twitter/X, Instagram, LinkedIn, Reddit, TikTok, Pinterest
   • Repository : GitHub, GitLab, BitBucket, StackOverflow
   • Shopping : Amazon, eBay, Etsy, AliExpress
   • Document : Google Docs, Notion, Trello, Jira, Confluence
   • PDF : Fichiers PDF directs
   • Image : Images directes, Imgur, Flickr
   • Newsletter : Lettres d'information (Substack, Revue, Mailchimp)
   • News : Sites d'actualités (BBC, CNN, Reuters, Le Monde, Le Figaro, The Guardian, New York Times, sites avec "news" dans le domaine)
   • Unknown : Contenu non identifié (sites personnels, blogs non catégorisés, outils spécialisés, contenu ne correspondant à aucune catégorie prédéfinie)

3. Identification des sites : Détection automatique du nom du site (YouTube, GitHub, Amazon, etc.)

4. Ajout de tags intelligents : Ajout automatique de tags pertinents selon le type :

   • video pour les vidéos
   • music pour la musique
   • radio pour les radios
   • podcast pour les podcasts
   • social pour les réseaux sociaux
   • news pour les actualités
   • repository, dev pour le code
   • shopping pour les achats
   • article, document, pdf, image, newsletter

Classification audio intelligente (Radio / Podcast / Musique)

L'application utilise un classifieur audio dédié (AudioClassifier) qui analyse l'URL avec un ordre de priorité strict pour éviter les faux positifs :

1. RADIO (priorité la plus haute) — Détecté si :

   • L'URL pointe vers un flux streaming direct (.m3u, .m3u8, .pls)
   • L'hôte contient un serveur de streaming (Icecast, Shoutcast, StreamTheWorld)
   • Le sous-domaine est stream.* ou live.*
   • L'URL est sur un agrégateur radio (TuneIn, Radio Garden, iHeartRadio, etc.)
   • Radio-Canada OHdio : paths /direct/, /premiere/, /audio-fil/ (hors balados)

2. PODCAST (priorité moyenne) — Détecté si :

   • L'URL est sur une plateforme dédiée (Apple Podcasts, Overcast, Pocket Casts, Anchor, etc.)
   • Spotify : paths /show/ ou /episode/ uniquement
   • Radio-Canada OHdio : paths contenant /balados/
   • Flux RSS/XML audio (.xml, .rss)

3. MUSIQUE (priorité standard) — Détecté si :

   • L'URL est sur un service de streaming musical (Deezer, Tidal, Apple Music, YouTube Music, Bandcamp, SoundCloud, Mixcloud, Beatport)
   • Spotify : paths /track/, /album/, /artist/ ou /playlist/

Exemple Spotify : open.spotify.com/track/... → Musique, open.spotify.com/show/... → Podcast, open.spotify.com/episode/... → Podcast

Avantages

• Organisation automatique : Vos liens sont catégorisés sans effort manuel
• Filtrage amélioré : Utilisez les tags auto-générés dans le menu latéral pour filtrer
• Statistiques précises : Le tableau de bord affiche la répartition par type de contenu
• Recherche optimisée : Les tags additionnels améliorent la recherche full-text

Utilisation

1. Allez dans Paramètres → Maintenance
2. Appuyez sur "Scanner et Classer"
3. Patientez pendant l'analyse (le temps dépend du nombre de liens)
4. Un message indique le nombre de liens mis à jour
5. Les nouveaux tags sont immédiatement disponibles pour le filtrage

Notes importantes

• Cette fonction ne modifie que les métadonnées (type, site, tags)
• Le contenu de vos liens (titre, description, URL) reste inchangé
• Les tags existants sont conservés, de nouveaux tags sont simplement ajoutés
• L'opération est sans risque et peut être répétée si nécessaire

🌐 Extraction de Métadonnées

• Extraction automatique des OpenGraph (titre, description, image) via JSoup
• Détection du type de contenu (article, vidéo, image, audio, code, repository, social, etc.)
• Estimation du temps de lecture
• Extraction du nom du site et du favicon
• Suggestion automatique de tags basée sur le domaine

📊 Tableau de Bord

• Statistiques d'utilisation (liens totaux, cette semaine, ce mois)
• Temps de lecture total et moyen
• Répartition par type de contenu
• Tags les plus utilisés
• Graphique d'activité sur 30 jours

<EFBFBD> Vérification des Liens (Health Check)

• Détection automatique des liens morts via WorkManager (toutes les 12h)
• Système de seuil : 3 échecs consécutifs avant de marquer un lien comme « mort »
• Filtrage intelligent (exclusion des notes, réseau local, IPs privées)
• Vérification manuelle à la demande depuis les paramètres
• Écran dédié de gestion des liens morts
• Exclusion de liens spécifiques du health check

<EFBFBD>💾 Import/Export

• Export JSON (format complet avec métadonnées)
• Export CSV (compatible Excel)
• Export HTML (format Netscape/Chrome bookmarks)
• Import depuis JSON (export ShaarIt)
• Import depuis HTML (bookmarks Chrome/Firefox)

🔄 Synchronisation

• Synchronisation automatique en arrière-plan (WorkManager)
• Mode offline-first : modifications en attente
• Résolution de conflits intelligente
• File d'attente des opérations

🔗 Intégration système

• Share Intent Android : Sauvegarde rapide depuis n'importe quelle app (URLs et fichiers texte/Markdown)
• Partage de fichiers : Import de fichiers .md, .txt directement comme notes Shaarli
• App Shortcuts : Accès rapide via appui long sur l'icône (Ajouter, Aléatoire, Rechercher, Collections)
• Quick Settings Tile : Tuile pour ajouter rapidement un lien
• Deep Links : Navigation directe via shaarit://feed, shaarit://add, shaarit://search, etc.
• Ouverture des liens dans le navigateur par défaut

🎨 Interface Utilisateur

• 15 thèmes sombres : ShaarIt, GitHub, Linear, Spotify, Notion, Discord, Dracula, One Dark Pro, Tokyo Night, Nord, Night Owl, Anthracite, Cyberpunk, Navy Élégance, Tons Terreux
• Design premium : Composants glassmorphism avec effets visuels
• Material Design 3 : Composants UI natifs Jetpack Compose
• Skeleton Loading : Chargement élégant avec shimmer effect
• Trois modes d'affichage : Liste détaillée, grille compacte, ou vue compacte
• Pull-to-refresh : Actualisation du flux par glissement
• Edge-to-Edge : Support des insets système (barre de statut, navigation)

---

🛠️ Stack Technique

Catégorie	Technologie
Langage	Kotlin 1.9.20
UI	Jetpack Compose (BOM 2023.08) + Material Design 3
Architecture	Clean Architecture + MVVM
Injection de dépendances	Dagger Hilt 2.48.1
Réseau	Retrofit 2.9.0 + Moshi 1.15.0 + OkHttp 4.12.0
Base de données locale	Room 2.6.1 (avec FTS4)
Pagination	Paging 3 (3.2.1)
Concurrence	Coroutines & Flow
Background work	WorkManager 2.9.0
Stockage sécurisé	AndroidX Security Crypto
Navigation	Navigation Compose 2.7.6
Images	Coil 2.6.0
Markdown	compose-markdown 0.4.1
HTML Parsing	JSoup 1.17.1
IA	Google Gemini AI SDK 0.9.0
Sérialisation	Kotlin Serialization 1.6.2
Compilation	AGP 8.13.2 + KSP 1.9.20

Compatibilité

• minSdk : 24 (Android 7.0)
• targetSdk : 34 (Android 14)
• compileSdk : 34
• JDK requis : 17+
• Compose Compiler : 1.5.4

---

📥 Installation

Prérequis utilisateur

• Un serveur Shaarli auto-hébergé (v0.12+) avec l'API v1 activée
• Un appareil Android 7.0+ ou un émulateur

Obtenir l'APK

Méthode 1 : Téléchargement direct

Récupérez le dernier APK depuis la section Releases.

Méthode 2 : Compilation depuis les sources

1. Clonez le repository :

git clone https://github.com/votre-username/ShaarIt.git
cd ShaarIt

2. Compilez l'APK debug :

./gradlew assembleDebug

L'APK sera généré dans app/build/outputs/apk/debug/

3. Ou compilez l'APK release (nécessite une configuration de signature) :

./gradlew assembleRelease

---

📖 Guide d'utilisation

Première configuration

1. Ouvrez l'application
2. Entrez l'URL de votre instance Shaarli (ex: https://monserveur.com/shaarli)
3. Entrez votre nom d'utilisateur et mot de passe
4. L'application générera automatiquement les tokens API nécessaires
5. (Optionnel) Configurez votre clé API Gemini dans Paramètres pour l'auto-tagging IA

Ajouter un lien

• Via l'app : Appuyez sur le bouton + et entrez l'URL
• Via le partage Android : Partagez n'importe quelle URL vers ShaarIt depuis n'importe quelle app
• Via Quick Settings : Ajoutez la tuile ShaarIt dans vos paramètres rapides
• Fichier Markdown : Partagez un fichier .md ou .txt pour l'importer comme note

Créer une note

• Sur l'écran d'ajout, basculez en mode Note (au lieu de Bookmark)
• Rédigez le titre et le contenu en Markdown
• La note sera sauvegardée sur votre instance Shaarli avec un identifiant unique

Intelligence Artificielle

1. Obtenez une clé API sur Google AI Studio
2. Allez dans Paramètres → Clé API Gemini et entrez votre clé
3. Lors de l'ajout d'un lien, appuyez sur le bouton IA pour analyser automatiquement l'URL
4. L'IA remplira le titre, la description et suggérera des tags pertinents

Organiser vos liens

• Utilisez les tags pour catégoriser vos liens
• Créez des collections pour regrouper des liens par thème
• Épinglez les liens importants pour un accès rapide

Mode hors-ligne

• Tous les liens sont stockés localement dans la base de données Room
• Les modifications sont synchronisées automatiquement quand la connexion est disponible
• Consultez vos favoris même sans connexion Internet

---

🏗️ Architecture

Le projet suit les principes de la Clean Architecture avec une séparation claire des couches :

├── data/                    # Couche de données
│   ├── api/                # API Retrofit (ShaarliApi)
│   ├── dto/                # Data Transfer Objects (Moshi)
│   ├── local/              # Base de données Room
│   │   ├── dao/           # Data Access Objects (Link, Tag, Collection)
│   │   ├── entity/        # Entités Room + FTS4
│   │   ├── converter/     # Type converters Room
│   │   └── database/      # Configuration de la DB
│   ├── mapper/             # Mappers DTO ↔ Entity ↔ Domain
│   ├── metadata/           # Extraction métadonnées (JSoup/OpenGraph)
│   ├── paging/             # PagingSource réseau
│   ├── sync/               # SyncManager + ConflictResolver + SyncWorker
│   ├── worker/             # LinkHealthCheckWorker
│   ├── export/             # BookmarkExporter (JSON, CSV, HTML)
│   └── repository/         # Implémentations (Link, Auth, Gemini)
├── domain/                 # Couche domaine
│   ├── model/             # Modèles métier (ShaarliLink, ShaarliTag, etc.)
│   ├── repository/        # Interfaces des repositories
│   └── usecase/           # Use cases (AnalyzeUrl, GenerateTags, Classify, Login)
├── presentation/           # Couche présentation
│   ├── feed/              # Écran principal + vues (List, Grid, Compact)
│   ├── add/               # Ajout de liens / notes
│   ├── edit/              # Édition de liens
│   ├── auth/              # Écran de connexion
│   ├── tags/              # Gestion des tags
│   ├── collections/       # Collections
│   ├── dashboard/         # Tableau de bord / statistiques
│   ├── deadlinks/         # Gestion des liens morts
│   ├── pinned/            # Liens épinglés
│   ├── settings/          # Paramètres (sync, export, IA, thèmes)
│   ├── help/              # Écran d'aide
│   └── nav/               # Navigation (NavGraph + Deep Links)
├── ui/                     # Composants UI réutilisables
│   ├── components/        # GlassCard, TagChip, MarkdownEditor, SkeletonLoader
│   └── theme/             # 15 thèmes + typographie + préférences
├── service/                # AddLinkTileService (Quick Settings)
└── core/                   # Utilitaires
    ├── di/                # Modules Hilt (App, Database, Network, Repository)
    ├── network/           # AuthInterceptor + HostSelectionInterceptor
    ├── storage/           # TokenManager (EncryptedSharedPreferences)
    └── util/              # JwtGenerator

---

🚀 Roadmap

Complété ✅

• Synchronisation en arrière-plan avec WorkManager
• Mode hors-ligne avec Room + architecture offline-first
• Éditeur Markdown (édition + prévisualisation + split)
• Extraction de métadonnées OpenGraph (JSoup)
• Collections manuelles et intelligentes
• Liens épinglés avec écran dédié
• App Shortcuts + Deep Links (shaarit://)
• Quick Settings Tile
• Tableau de bord analytique (statistiques, graphiques)
• Import/Export (JSON, CSV, HTML Netscape)
• 15 thèmes sombres premium
• Intelligence Artificielle (Google Gemini) — auto-tagging, analyse d'URL, classification
• Recherche FTS4 (full-text search) + filtres multi-tags
• Détection et gestion des liens morts (Health Check)
• Support des notes Markdown (pas uniquement des URLs)
• Partage de fichiers .md / .txt via Share Intent
• Skeleton Loading (shimmer effect)
• Résolution de conflits de synchronisation
• Synchronisation des collections via le serveur Shaarli
• Optimisations de performance — R8/ProGuard, Baseline Profiles, sync incrémentale
• Recherche FTS4 activée dans le repository — Moteur FTS4 intégré dans LinkRepositoryImpl
• Migrations Room explicites — MIGRATION_4_5 explicite + fallback ciblé pour v1-v3

Prochaines étapes 🔜

• Mode lecture sans distraction (Reader Mode) pour les articles
• Widget d'accueil interactif (Glance)
• Partage de collections entre utilisateurs
• Support multi-instances Shaarli
• Verrouillage biométrique
• Rappels de lecture (« Lire plus tard » avec notifications)
• Voice Input dans la recherche et l'ajout de lien
• Adaptive Layouts pour tablettes et foldables
• Thème clair et Material You (Monet) dynamique sur Android 12+

---

📄 Documentation

Document	Description
Performance & UX Optimale	Analyse de performance complète, 24 optimisations identifiées, plan d'action priorisé
Analyse et Améliorations	Propositions d'améliorations fonctionnelles et architecturales
Rapport d'Audit v2	Audit UX « Next Level » — micro-interactions, IA, ergonomie
Instructions de Build Release	Guide de création du keystore, signature et build release
Roadmap Prochaines Fonctionnalités	Analyse détaillée des 9 fonctionnalités à implémenter (Reader Mode, Widget, Biométrie, Material You…)

---

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à :

• Ouvrir une issue pour signaler un bug ou suggérer une fonctionnalité
• Soumettre une pull request
• Améliorer la documentation

Signaler un bug

1. Vérifiez que le bug n'a pas déjà été signalé
2. Ouvrez une issue avec :
   • Description claire du problème
   • Étapes pour reproduire
   • Comportement attendu vs réel
   • Version Android et de l'app
   • Logs si disponibles

---

📝 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

---

🙏 Remerciements

• Shaarli - Le projet original de gestionnaire de favoris
• Jetpack Compose - Framework UI moderne d'Android
• Google Gemini - IA générative pour l'enrichissement intelligent
• JSoup - Parsing HTML pour l'extraction de métadonnées
• Coil - Chargement d'images optimisé pour Compose
• La communauté open source pour les excellentes bibliothèques utilisées

---

_{Fait avec ❤️ pour la communauté Shaarli}