# 🌌 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

```bash
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)
```bash
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

```bash
node server/index.mjs
```

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

### Structure des données

Format JSON compatible Obsidian :

```json
{
  "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 !