🌌 ObsiViewer — Explorateur de voûte Obsidian

ObsiViewer est une application Angular 20 qui permet de parcourir une voûte Obsidian en lecture seule : navigation dans l’arborescence des notes, rendu Markdown enrichi, visualisation du graphe et filtrage avancé par tags ou dates.

📝 Mode démo par défaut : l’interface repose sur des données générées par VaultService. Vous pouvez connecter ObsiViewer à vos fichiers Markdown via le serveur Express fourni.

---

🚀 Aperçu rapide

• Framework : Angular + TailwindCSS
• Rendu Markdown : MarkdownService (supporte Mermaid, KaTeX, surlignage de code)
• Visualisations :
  • Explorateur de fichiers (app/components/file-explorer/)
  • Graphe de liens (app/components/graph-view/)
  • Vue tags (app/components/tags-view/)
  • Recherche + calendrier (intégré à app.component.simple.html)
• Backend optionnel : serveur Express (server/index.mjs) qui lit la voûte physique (vault/) et expose une API REST.

---

🧰 Prérequis

• Node.js 20+ et npm (node --version)
• Angular CLI (facultatif mais pratique) : npm install -g @angular/cli
• Docker (facultatif) pour utiliser les scripts situés dans docker/ et docker-compose/

---

⚙️ Installation & scripts utiles

npm install      # Installe toutes les dépendances
npm run dev      # Lance l'app en mode développement (http://localhost:3000)
npm run build    # Compile la version production dans dist/
npm run preview  # Sert la build de prod avec ng serve

👉 Le port de dev et la configuration de build sont définis dans angular.json.

---

🗂️ Structure du dépôt

• src/ : composant principal app.component.ts, vue simplifiée, composants UI, services, types
• server/ : serveur Express pour charger vos notes locales et fournir l’API /api
• vault/ : emplacement attendu des fichiers Markdown (créé au démarrage du serveur)
• docker/ & docker-compose/ : scripts et configurations pour l’exécution en conteneurs
• index.tsx : point d’entrée Angular (bootstrap sans zone)
• metadata.json : métadonnées pour l’intégration AI Studio

---

🔌 Configurer l’API locale (optionnel)

npm run build            # génère dist/
node server/index.mjs    # lance l'API + serveur statique sur http://localhost:4000

Assurez-vous que vos notes Markdown se trouvent dans vault/. L'API expose :

• GET /api/health
• GET /api/vault
• GET /api/vault/bookmarks - Récupère les favoris depuis <vault>/.obsidian/bookmarks.json
• PUT /api/vault/bookmarks - Sauvegarde les favoris (avec gestion de conflits via If-Match)
• GET /api/files/metadata
• GET /api/files/by-date?date=2025-01-01
• GET /api/files/by-date-range?start=...&end=...

---

⭐ Gestion des favoris (Bookmarks)

ObsiViewer implémente une gestion complète des favoris 100% compatible avec Obsidian, utilisant <vault>/.obsidian/bookmarks.json comme source unique de vérité.

Fonctionnalités

• Synchronisation bidirectionnelle : Les modifications dans ObsiViewer apparaissent dans Obsidian et vice-versa
• Deux modes d'accès :
  • File System Access API (préféré) : Sélectionnez votre dossier vault directement depuis le navigateur
  • Serveur Bridge : L'API Express lit/écrit le fichier .obsidian/bookmarks.json
• Opérations complètes : Créer, modifier, supprimer, réorganiser, grouper
• Import/Export : Importer ou exporter vos favoris au format JSON Obsidian
• Détection de conflits : Alerte si le fichier a été modifié en externe avec options de résolution
• Sauvegarde automatique : Debouncing de 800ms pour éviter les écritures excessives
• Interface responsive : Optimisée pour desktop et mobile avec thèmes clair/sombre

Comment utiliser

Mode Navigateur (File System Access API)

1. Cliquez sur "Connect Vault" dans le panneau Favoris
2. Sélectionnez le dossier racine de votre vault Obsidian
3. Accordez les permissions de lecture/écriture
4. ObsiViewer accède directement à .obsidian/bookmarks.json

⚠️ Nécessite Chrome 86+, Edge 86+, ou Opera 72+ (pas de support Firefox/Safari)

Mode Serveur

node server/index.mjs

Le serveur lit/écrit automatiquement vault/.obsidian/bookmarks.json.

Structure des données

Format JSON compatible Obsidian :

{
  "items": [
    {
      "type": "group",
      "ctime": 1704067200000,
      "title": "Mes Notes",
      "items": [
        {
          "type": "file",
          "ctime": 1704067201000,
          "path": "Notes/important.md",
          "title": "Note Importante"
        }
      ]
    }
  ]
}

Types supportés : group, file (dossiers, recherches, headings, blocks parsés mais non affichés).

Architecture technique

src/core/bookmarks/
├── types.ts                    # Types TypeScript
├── bookmarks.utils.ts          # Opérations arbre + validation
├── bookmarks.repository.ts     # Adapters de persistance
└── bookmarks.service.ts        # Service Angular avec Signals

src/components/
├── bookmarks-panel/            # Composant principal
└── bookmark-item/              # Item d'arborescence

Le service utilise les Signals Angular pour la réactivité et implémente un système de sauvegarde automatique avec debounce.

---

🐳 Exécution avec Docker (facultatif)

• docker/build-img.ps1 / docker/deploy-img.ps1 pour construire et pousser une image locale
• docker/Dockerfile.origi pour une build manuelle (docker build ...)
• docker-compose/docker-compose.yml pour orchestrer un conteneur préconfiguré

💡 Pensez à personnaliser les fichiers .env (.env.local, docker-compose/.env) avant toute utilisation réelle.

---

🧪 Tests & qualité

• Aucun test automatisé n’est fourni pour l’instant.
• Ajoutez vos propres suites (ng test, ng e2e) selon vos besoins.

---

⚠️ Points d’attention

• Les scripts Docker hérités supposent la présence d’un dossier server/ et d’un schéma db/schema.sql (non inclus ici).
• Les secrets fournis en exemple dans les fichiers .env doivent être remplacés avant toute utilisation en production.
• Le rendu Markdown peut nécessiter des adaptations pour des voûtes Obsidian complexes.

---

📚 Ressources

• Angular : https://angular.dev/
• CLI Angular (ng serve) : https://angular.dev/cli/serve
• Guide Docker Compose : voir docker-compose/README.md

---

✨ Bonne exploration dans ObsiViewer !