docs: documentation fonctionnelle, technique et installation
This commit is contained in:
@@ -0,0 +1,124 @@
|
||||
# Architecture
|
||||
|
||||
Pena (`Pena-tauri`) est une application [Tauri 2](https://tauri.app/) : un **backend Rust**
|
||||
expose des commandes à un **frontend web** (HTML/CSS/JS vanilla, sans bundler). Le frontend
|
||||
est servi en fichiers statiques depuis `src/`, le backend est compilé dans `src-tauri/`.
|
||||
|
||||
L'ensemble suit une **Clean Architecture** stricte, côté Rust comme côté JS.
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
```
|
||||
┌──────────────────────────── Frontend (src/, JS vanilla) ────────────────────────────┐
|
||||
│ ui/ — composants d'affichage (home, sidebar, reader, css-modal) │
|
||||
│ state/ — état global minimal (app-state) │
|
||||
│ services/ — appels Tauri via invoke (markdown, files, watcher, themes) │
|
||||
│ router.js — navigation entre vues (accueil / lecteur) │
|
||||
└──────────────────────────────────────┬───────────────────────────────────────────────┘
|
||||
│ window.__TAURI__.core.invoke(...)
|
||||
│ window.__TAURI__.event.listen(...)
|
||||
┌──────────────────────────────────────┴──── Backend (src-tauri/src/, Rust) ───────────┐
|
||||
│ commands/ — points d'entrée #[tauri::command] (render, watch, theme) │
|
||||
│ application/ — services métier (render_service, file_service, theme_service) │
|
||||
│ infrastructure/ — implémentations concrètes (comrak, notify, fs, thèmes statiques) │
|
||||
│ domain/ — entités et traits purs (MarkdownRenderer, ThemeRepository…) │
|
||||
│ lib.rs — point d'assemblage (wiring + enregistrement des commandes) │
|
||||
└───────────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Backend Rust — couches
|
||||
|
||||
Le code Rust (`src-tauri/src/`) est découpé en quatre couches, avec des règles de dépendance
|
||||
strictes.
|
||||
|
||||
| Couche | Rôle | Peut dépendre de | Ne doit PAS dépendre de |
|
||||
|---|---|---|---|
|
||||
| `domain/` | Entités et traits purs, zéro dépendance externe | rien | `application`, `infrastructure`, `commands` |
|
||||
| `application/` | Services métier (orchestration des cas d'usage) | `domain` | `infrastructure`, `commands` |
|
||||
| `infrastructure/` | Implémentations concrètes des traits du domaine | `domain` | `application`, `commands` |
|
||||
| `commands/` | Commandes exposées à Tauri | `application`, `domain` | `infrastructure` (directement) |
|
||||
|
||||
### `domain/`
|
||||
Définit les contrats, sans aucune dépendance technique :
|
||||
- `markdown.rs` — trait `MarkdownRenderer { fn render(&self, content: &str) -> String }`
|
||||
et struct `RenderOptions` (tables, strikethrough, autolink, tasklist).
|
||||
- `theme.rs` — struct `Theme { id, label }` et trait
|
||||
`ThemeRepository { fn list() -> Vec<Theme>; fn get_css(id) -> Option<String> }`.
|
||||
|
||||
### `application/`
|
||||
Orchestration métier, dépend uniquement du domaine :
|
||||
- `render_service.rs` — `render_string()` (rendu d'une chaîne) et `render_file()`
|
||||
(lecture du fichier puis rendu).
|
||||
- `file_service.rs` — `list_markdown_files()` : valide le répertoire, collecte les `.md`,
|
||||
trie alphabétiquement.
|
||||
- `theme_service.rs` — `list_themes()` et `get_theme_css()`, délégués au repository.
|
||||
|
||||
### `infrastructure/`
|
||||
Implémentations concrètes des traits du domaine :
|
||||
- `comrak_renderer.rs` — `ComrakRenderer` (toutes les extensions activées, pour les
|
||||
fichiers) et `ComrakPreviewRenderer` (sans extensions, pour les aperçus rapides). Fournit
|
||||
aussi `syntax_css_for_theme()` pour générer le CSS de coloration `syntect`. La syntaxe
|
||||
TypeScript est chargée depuis `resources/syntaxes/TypeScript.sublime-syntax`.
|
||||
- `file_repository.rs` — `collect_md_files()` (parcours récursif, ignore les fichiers
|
||||
cachés, ne retient que les `.md`) et `read_file()`.
|
||||
- `notify_watcher.rs` — boucle de débounce (80 ms) qui filtre les événements de la crate
|
||||
`notify` et émet l'événement Tauri `file-changed`.
|
||||
- `theme_repository.rs` — `StaticThemeRepository` : les 6 thèmes et leur CSS sont intégrés
|
||||
au binaire via `include_str!()` (fichiers `resources/themes/*.css`).
|
||||
|
||||
### `commands/`
|
||||
Points d'entrée Tauri qui instancient les implémentations concrètes et appellent les
|
||||
services. Voir la référence complète : [Commandes Tauri](2.2-Commandes-Tauri.md).
|
||||
|
||||
### `lib.rs` — point d'assemblage
|
||||
Seul endroit où les implémentations concrètes sont câblées. Il :
|
||||
- enregistre les plugins `tauri-plugin-fs` et `tauri-plugin-dialog` ;
|
||||
- gère l'état global `WatcherState` (un seul watcher actif à la fois) ;
|
||||
- enregistre les 8 commandes via `generate_handler![]`.
|
||||
|
||||
## Frontend JS — couches
|
||||
|
||||
Le code JS (`src/`) suit le même esprit de séparation :
|
||||
|
||||
| Dossier | Rôle | Peut dépendre de |
|
||||
|---|---|---|
|
||||
| `ui/` | Composants d'affichage, sans logique métier ni appel Tauri direct | `services/`, `state/` |
|
||||
| `state/` | État global de l'application (`app-state.js`) | — |
|
||||
| `services/` | Appels Tauri (`invoke`) et logique de données | API Tauri |
|
||||
| `router.js` | Navigation entre les vues (accueil / lecteur), orchestrateur | `services/`, `ui/`, `state/` |
|
||||
|
||||
**Règle importante** : les composants `ui/` ne font **jamais** d'appel Tauri directement ;
|
||||
ils passent toujours par un service de `services/`.
|
||||
|
||||
### Services frontend
|
||||
- `services/markdown.js` — `render_markdown`, `convert_file`
|
||||
- `services/files.js` — `list_md_files`
|
||||
- `services/watcher.js` — `start_watch`, `stop_watch`, écoute de `file-changed`
|
||||
(présent mais non utilisé par l'UI)
|
||||
- `services/themes.js` — `list_themes`, `get_theme_css`
|
||||
|
||||
## Dépendances Rust principales
|
||||
|
||||
| Crate | Rôle |
|
||||
|---|---|
|
||||
| `tauri` (+ `tauri-plugin-fs`, `tauri-plugin-dialog`) | Framework applicatif, IPC, événements, dialogues |
|
||||
| `comrak` | Rendu CommonMark + extensions |
|
||||
| `syntect` | Coloration syntaxique des blocs de code |
|
||||
| `notify` | Surveillance du système de fichiers |
|
||||
| `serde` / `serde_json` | Sérialisation des DTO et payloads |
|
||||
|
||||
## Ressources intégrées au binaire
|
||||
|
||||
| Ressource | Emplacement | Usage |
|
||||
|---|---|---|
|
||||
| Thèmes rapides | `src-tauri/resources/themes/*.css` | Servis par `get_theme_css` |
|
||||
| Syntaxe TypeScript | `src-tauri/resources/syntaxes/TypeScript.sublime-syntax` | Coloration des blocs TS |
|
||||
|
||||
Elles sont incluses à la compilation (`include_str!`), donc l'application n'a pas besoin de
|
||||
fichiers externes pour fonctionner.
|
||||
|
||||
## Voir aussi
|
||||
|
||||
- [Commandes Tauri](2.2-Commandes-Tauri.md)
|
||||
- [Build et compilation](../3-installation/3.3-Build.md)
|
||||
- [Vue d'ensemble fonctionnelle](../1-fonctionnel/1.1-Vue-d-ensemble.md)
|
||||
Reference in New Issue
Block a user