# 🌌 ObsiViewer — Explorateur de voûte Obsidian

## 📋 Description

ObsiViewer est une application web **Angular 20** moderne et performante qui permet d'explorer et visualiser une voûte Obsidian en lecture seule. Conçue comme une alternative légère pour consulter vos notes Markdown depuis n'importe quel navigateur, elle offre une expérience riche avec navigation fluide, rendu Markdown avancé, visualisation interactive du graphe de connaissances et recherche compatible Obsidian.

**Cas d'usage principaux**
- 📖 Consultation de votre vault Obsidian depuis un navigateur
- 🌐 Partage de vos notes en lecture seule (hébergement web)
- 📱 Accès mobile optimisé à votre base de connaissances
- 🔍 Exploration visuelle des liens entre vos notes
- 📊 Analyse du vault via graphe et statistiques

> 📝 Mode démo par défaut : l'interface fonctionne avec des données générées par `VaultService`. Connectez-la à vos fichiers Markdown réels via le serveur Express pour une utilisation complète.

---

## ✨ Fonctionnalités Principales

### 🗂️ Navigation et Organisation
- **Explorateur de fichiers** : Arborescence complète avec dossiers pliables/dépliables
- **Recherche avancée** : Moteur de recherche compatible Obsidian avec opérateurs (`path:`, `tag:`, `line:`, etc.)
- **Vue Tags** : Visualisation et filtrage par tags avec compteurs
- **Calendrier** : Navigation temporelle par dates de création/modification
- **Favoris (Bookmarks)** : Gestion complète compatible avec `.obsidian/bookmarks.json`
- **Breadcrumbs** : Navigation contextuelle avec fil d'Ariane

### 📝 Rendu Markdown
- **Markdown enrichi** : Support complet de la syntaxe Obsidian
- **Wikilinks** : `[[liens internes]]` avec preview au survol et navigation
- **Callouts** : Blocs d'information stylisés (note, warning, info, etc.)
- **Syntax highlighting** : Coloration syntaxique pour 100+ langages via highlight.js
- **Diagrammes Mermaid** : Rendu des diagrammes et flowcharts
- **Mathématiques** : Support LaTeX/KaTeX pour formules mathématiques
- **Tables avancées** : Multi-markdown tables avec fusion de cellules
- **Task lists** : Listes de tâches interactives
- **Footnotes** : Notes de bas de page
- **Embeddings** : Images et attachements avec résolution intelligente

### 🕸️ Graphe de Connaissances
- **Visualisation interactive** : Graphe de liens basé sur d3-force
- **Physique réaliste** : Simulation de forces pour placement optimal
- **Drag & Drop** : Déplacement et fixation des nœuds
- **Filtres avancés** : Tags, attachments, orphelins, recherche
- **Color Groups** : Coloration personnalisée par requêtes
- **Paramètres complets** : 14+ options (forces, apparence, affichage)
- **Persistance** : Sauvegarde dans `.obsidian/graph.json`
- **Mode focus** : Centré sur une note avec profondeur configurable

### 🔍 Recherche et Filtrage
- **Moteur de recherche Obsidian-compatible** avec tous les opérateurs
- **Assistant de requêtes** : Autocomplétion intelligente avec suggestions
- **Historique** : Mémorisation des 10 dernières recherches par contexte
- **Highlighting** : Mise en évidence des résultats
- **Tri multiple** : Pertinence, nom, date de modification
- **Preview** : Extraits contextuels dans les résultats

### 🎨 Interface Utilisateur
- **Design moderne** : Interface soignée inspirée d'Obsidian
- **Dark/Light mode** : Thèmes clair et sombre avec transition fluide
- **Responsive** : Optimisé desktop, tablette et mobile
- **Sidebar redimensionnable** : Ajustement de la largeur des panneaux
- **Keyboard shortcuts** : Raccourcis clavier (Alt+R, Alt+D)
- **Animations fluides** : 60fps avec optimisations performance

---

## 🧰 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`.

---

## 🏗️ Architecture

### Stack Technique

| Technologie | Version | Usage |
|-------------|---------|-------|
| Angular | 20.3.x | Framework (Signals, Standalone Components) |
| TypeScript | 5.8.x | Langage (mode strict) |
| TailwindCSS | 3.4.x | Styling et design system |
| Angular CDK | 20.2.x | Overlay, drag-drop |
| RxJS | 7.8.x | Programmation réactive |
| Express | 5.1.x | API REST backend |
| Chokidar | 4.0.x | File watching |
| Markdown-it | 14.1.x | Parsing/rendu Markdown |
| highlight.js | 11.10.x | Syntax highlighting |
| mermaid | 11.12.x | Diagrammes |
| d3-force | 3.0.x | Physique du graphe |
| date-fns | 4.1.x | Dates |

### Patterns

- Signals pour la réactivité fine-grained
- Standalone Components (sans NgModules)
- Repository Pattern (FileSystem / Server / Mémoire)
- Services pour la logique métier
- Change Detection OnPush
- Bootstrap sans Zone.js

### Structure du Projet

```
ObsiViewer/
├── src/
│   ├── app/
│   │   ├── core/                 # Services core (download, theme)
│   │   └── graph/                # Graph settings & runtime
│   ├── components/               # UI (bookmarks, graph, search, calendar, etc.)
│   ├── core/                     # bookmarks/, graph/, search/, services/
│   ├── services/                 # vault.service, markdown.service, etc.
│   ├── shared/                   # Overlays, composants communs
│   ├── styles/                   # CSS globaux, tokens
│   ├── types/                    # Types TS
│   └── app.component.ts          # Composant racine
├── server/index.mjs              # API Express + fichiers statiques
├── docker*/                      # Docker & Compose
├── docs/                         # Documentation détaillée
├── vault/                        # Voûte Obsidian (créée au démarrage)
├── index.tsx                     # Bootstrap Angular
├── angular.json, tsconfig.json   # Configs
└── package.json                  # Dépendances
```

---

## 🔌 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 :

#### Endpoints Principaux

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/health` | État du serveur |
| GET | `/api/vault` | Liste complète des notes avec contenu |
| GET | `/api/vault/events` | Server-Sent Events pour live reload |
| GET | `/api/files/metadata` | Métadonnées de tous les fichiers |
| GET | `/api/files/by-date` | Fichiers créés/modifiés à une date |
| GET | `/api/files/by-date-range` | Fichiers dans un intervalle |
| GET | `/api/vault/bookmarks` | Favoris `.obsidian/bookmarks.json` |
| PUT | `/api/vault/bookmarks` | Sauvegarde favoris (avec If-Match) |
| GET | `/api/vault/graph` | Configuration graphe `.obsidian/graph.json` |
| PUT | `/api/vault/graph` | Sauvegarde configuration graphe |
| GET | `/api/attachments/resolve` | Résolution intelligente d'attachements |

#### Fonctionnalités Serveur

- **Live Reload** : Détection des changements de fichiers via Chokidar
- **Server-Sent Events** : Notifications en temps réel des modifications
- **Résolution d'attachements** : Recherche intelligente dans l'arborescence
- **Atomic Writes** : Écritures sécurisées avec fichiers temporaires
- **Conflict Detection** : Gestion des conflits avec hash de révision
- **CORS Safe** : Configuration proxy pour développement

---

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

### Tests unitaires

Scripts disponibles:

```bash
npm run test:markdown  # src/services/markdown.service.spec.ts
# Ou exécuter un test spécifique (exemples):
node --loader ts-node/esm --test src/services/wikilink-parser.service.spec.ts
node --loader ts-node/esm --test src/core/bookmarks/bookmarks.service.spec.ts
node --loader ts-node/esm --test src/core/bookmarks/bookmarks.utils.spec.ts
node --loader ts-node/esm --test src/core/search/search-parser.spec.ts
```

### Tests manuels recommandés

- **Wikilinks**: `[[note]]`, `[[note|Alias]]`, `[[note#Section]]`, `[[note#^block]]` → navigation + preview au survol.
- **Graph View**: drag & drop, options (forces, affichage), groupes colorés, filtres (tags/attachments/orphans).
- **Bookmarks**: connexion vault, création/édition/suppression, drag & drop, import/export, détection de conflits.
- **Recherche**: opérateurs `path:`, `file:`, `tag:`, `line:`, `section:`, `[property]`, OR/NOT/()``, exact phrases, wildcard, regex.

---

## 🛠️ Développement

### Standards de code
- TypeScript strict, architecture Angular 20 (Standalone + Signals)
- ChangeDetection OnPush, composantisation claire
- TailwindCSS (dark mode via classe `dark`/`[data-theme="dark"]`)

### Conventions
- Composants: `kebab-case.component.ts`, Services: `kebab-case.service.ts`
- Types/Interfaces: `PascalCase`, constantes: `SCREAMING_SNAKE_CASE`

### Variables d’environnement
| Variable | Description | Défaut |
|----------|-------------|--------|
| `PORT` | Port du serveur Express | `4000` |
| `NODE_ENV` | Environnement | `development` |
| `VAULT_PATH` | Chemin du vault (optionnel) | `./vault` |

### Contribution
1. Fork → branche `feature/x`
2. Commits conventionnels (`feat:`, `fix:`, `docs:`...)
3. PR avec description claire + captures si UI

---

## 🔐 Sécurité
- Lecture seule des notes (écriture uniquement sur `.obsidian/bookmarks.json` et `.obsidian/graph.json`)
- Pas d’authentification intégrée (prévoir un reverse proxy/SSO en production)
- Résolution d’attachements sécurisée (vérifications d’existence)
- Échappement du HTML pour réduire les risques XSS via Markdown
- Ne pas committer de secrets `.env`

---

## 📈 Performance
- Wikilinks: ~30ms/100 liens (voir `IMPLEMENTATION_SUMMARY.md`)
- Graph 1000 nœuds: ~400ms initial, 60fps animation
- Recherche complexe 2000+ notes: <200ms (voir `SEARCH_COMPLETE.md`)
- Optimisations: Signals, OnPush, LRU cache (previews), debounce (250–800ms), rAF, zoneless bootstrap

---

## 🐛 Problèmes connus
- File System Access API non supportée sur Firefox/Safari → utiliser le mode serveur Express
- Zoom/Pan du graphe non implémenté (prévu via `d3-zoom`)
- `bookmark-item`: édition inline TODO (voir commentaire dans le code)
- Contexte menu z-index (UI) à ajuster dans SCSS
- Très grands vaults (>5000 notes): envisager filtrage/virtualisation

---

## ⚠️ 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.

---

## 📝 Changelog

Voir les fichiers de documentation pour historiques détaillés :
- `IMPLEMENTATION_SUMMARY.md` - Wikilinks & Graph View
- `SEARCH_COMPLETE.md` - Système de recherche
- `docs/BOOKMARKS_CHANGELOG.md` - Évolution des favoris
- `GRAPH_VIEW_SEARCH_IMPLEMENTATION.md` - Graph & Search Assistant

### Version Actuelle : 0.0.0 (Développement)

**Fonctionnalités majeures** :
- ✅ Navigation complète vault Obsidian
- ✅ Rendu Markdown enrichi avec wikilinks
- ✅ Graph View interactif avec parité Obsidian
- ✅ Système de recherche avancée
- ✅ Gestion bookmarks synchronisée
- ✅ Live reload avec SSE
- ✅ Dark/Light mode
- ✅ Responsive mobile

## 📄 Licence

**Pas de licence spécifiée** - Usage libre pour développement et consultation.

> ⚠️ **Note** : Ajoutez une licence appropriée (MIT, Apache 2.0, GPL, etc.) avant publication ou distribution.

## 👥 Auteurs et Contributeurs

**Développement principal** : Projet développé avec assistance AI (Claude/Anthropic)

**Technologies et Inspirations** :
- [Obsidian](https://obsidian.md/) - Inspiration design et fonctionnalités
- [Angular](https://angular.dev/) - Framework
- [TailwindCSS](https://tailwindcss.com/) - Styling
- [D3.js](https://d3js.org/) - Visualisation graphe

## 🔗 Liens Utiles

### Documentation Projet
- [Architecture Complète](./docs/) - Documentation technique détaillée
- [Guide Bookmarks](./docs/BOOKMARKS_IMPLEMENTATION.md) - Système de favoris
- [Guide Wikilinks](./docs/WIKILINKS_README.md) - Liens internes
- [Guide Recherche](./docs/SEARCH_IMPLEMENTATION.md) - Moteur de recherche
- [Guide Graph](./docs/GRAPH_SETTINGS.md) - Configuration graphe

### Resources Externes
- [Angular Framework](https://angular.dev/)
- [Angular CLI](https://angular.dev/cli)
- [Obsidian Documentation](https://help.obsidian.md/)
- [Markdown-it](https://markdown-it.github.io/)
- [D3-Force Documentation](https://github.com/d3/d3-force)
- [TailwindCSS Docs](https://tailwindcss.com/docs)
- [Docker Compose Guide](./docker-compose/README.md)

### API Documentation
- **File System Access API** : [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API)
- **Server-Sent Events** : [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)

---

## 🎯 Quick Start Complet

```bash
# 1. Installation
git clone <repo-url>
cd ObsiViewer
npm install

# 2. Démarrage développement (mode demo)
npm run dev
# → Ouvrir http://localhost:3000

# 3. Avec votre vault (mode serveur)
mkdir -p vault
# Copier vos notes .md dans vault/
npm run build
node server/index.mjs
# → Ouvrir http://localhost:4000

# 4. Production
npm run build
# Déployer le contenu de dist/ sur votre hébergement
```

---

✨ **Bonne exploration dans ObsiViewer !** ✨

💡 **Besoin d'aide ?** Consultez la documentation dans `/docs` ou ouvrez une issue.

🚀 **Prêt pour la production ?** Voir `ROADMAP.md` pour les prochaines étapes.