# enveloppe/obsidian-enveloppe architecture

> Architecture diagram of the GitHub repository enveloppe/obsidian-enveloppe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/enveloppe/obsidian-enveloppe
- Repository: https://github.com/enveloppe/obsidian-enveloppe

## Overview

Based on our analysis of the file tree and README, we’re dealing with an Obsidian plugin that serves as a GitHub-based vault publisher. In short, this project converts your Obsidian vault—transforming wikilinks, handling Dataview queries, cleaning up the repository, and more—so that your notes can be published on a GitHub repository (using templates like Jekyll, Mkdocs, Hugo, etc.).

##### Main Components
a. Commands Module – (located in src/commands)
- Contains multiple command scripts (upload, refresh, purge, etc.) that act as the interface between user input and the plugin’s operations.
b. Conversion Engine – (located in src/conversion)
- Implements the conversion logic including:
– Converting Obsidian wikilinks to Markdown links.
– Handling Dataview queries, inline syntax, and link updates.
– Managing file paths and link repair.
c. GitHub Communication Module – (located in src/GitHub)
- Manages API interactions (branch creation, file upload, branch merging, conflict handling, etc.).
d. Configuration & Settings – (scattered in src/settings, manifest.json, etc.)
- Governs user settings, initial configuration, and integration options (like GitHub token management).
e. Internationalization Support – (in src/i18n)
- Manages language and localization files.
f. Utility & Type Definitions – (src/utils and src/@types)
- Contains helper functions for validation, logging, and shared types/interfaces.

##### Relationships and Data Flows
- User actions in Obsidian trigger specific commands which are handled by the Commands Module.
- Commands invoke the Conversion Engine to process markdown (translating wikilinks to standard Markdown, fixing folder notes etc.).
- Once conversion is completed, the GitHub Module takes over to push the content to the appropriate branch and repository.
- Settings and configuration data (e.g., repository details, GitHub token) are referenced throughout the process.
- Utility modules support logging, error validation, and data manipulation across these operations.

##### Architectural Patterns and Design Principles
- Modular Separation – Each major responsibility (commands, conversion, GitHub interaction, configuration) is encapsulated in its own set of directories.
- Clear Separation of Concerns – UI/Command handling is separated from data conversion and external communication.
- Extensibility – The plugin is designed so that new commands or conversion routines can be added without significant restructuring.
- Emphasis on configuration – Settings and internationalization are independently handled to keep the core logic clean.

##### Incorporate Relevant Technologies
- Written in TypeScript, using modern JavaScript features.
- Uses Node tooling (esbuild, Dockerfile for containerization, etc.) and GitHub workflows for CI/CD.
- Utilizes external libraries for internationalization (i18next) and might integrate with Obsidian’s API conventions.

## Diagram (Mermaid)

```mermaid
graph TD
    UC["User Command"]:::user
    CM["Commands Module"]:::module
    CE["Conversion Engine"]:::module
    GH["GitHub Communication Module"]:::module
    CS["Configuration & Settings"]:::config
    I18N["Internationalization Support"]:::i18n
    UT["Utility & Type Definitions"]:::util

    UC -->|"triggers"| CM
    CM -->|"invokes"| CE
    CE -->|"uploadsTo"| GH
    GH -->|"errorFeedback"| CM

    CM -->|"readsConfig"| CS
    CE -->|"readsConfig"| CS
    GH -->|"readsConfig"| CS

    CE -->|"usesI18n"| I18N

    CM -->|"logsUtil"| UT
    CE -->|"usesUtil"| UT
    GH -->|"logsUtil"| UT

    click CM "https://github.com/enveloppe/obsidian-enveloppe/tree/master/src/commands"
    click CE "https://github.com/enveloppe/obsidian-enveloppe/tree/master/src/conversion"
    click GH "https://github.com/enveloppe/obsidian-enveloppe/tree/master/src/GitHub"
    click CS "https://github.com/enveloppe/obsidian-enveloppe/tree/master/src/settings"
    click CS "https://github.com/enveloppe/obsidian-enveloppe/blob/master/manifest.json"
    click I18N "https://github.com/enveloppe/obsidian-enveloppe/tree/master/src/i18n"
    click UT "https://github.com/enveloppe/obsidian-enveloppe/tree/master/src/utils"
    click UT "https://github.com/enveloppe/obsidian-enveloppe/tree/master/src/@types"

    classDef user fill:#f4d03f,stroke:#333,stroke-width:2px;
    classDef module fill:#85c1e9,stroke:#2e86c1,stroke-width:2px;
    classDef config fill:#82e0aa,stroke:#27ae60,stroke-width:2px;
    classDef i18n fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
    classDef util fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
```
