# cristianvasquez/vault-triplifier architecture

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

- Interactive diagram: https://gitdiagram.com/cristianvasquez/vault-triplifier
- Repository: https://github.com/cristianvasquez/vault-triplifier

## Overview

##### Project Type and Purpose
- This is an open-source command-line/library tool (“Vault triplifier”) that reads markdown files and produces RDF (graph data) as output.
- It’s not a full-stack web app; it’s a data-processing pipeline with a clear input (markdown vault) and output (RDF/Turtle).

##### File Structure
- Top-level:
- index.js / example.js: CLI entry points and usage examples
- package.json / package-lock.json: NPM packaging, dependencies
- src/: the core implementation
- test/: automated tests and fixtures
- src/ subdirectories:
- indexers/: discover and read markdown files (vault.js)
- triplifiers/: convert parsed data into RDF triples (astTriplifier, canvasTriplifier, etc.)
- termMapper/: apply vocabulary mappings (defaultTermMapper, defaultCustomMapper)
- strings/: URI and string utilities
- postProcess.js: final transformations and serialization
- namespaces.js: RDF namespace declarations
- canvas-to-RDF.js, markdown-to-RDF.js: high-level orchestration for different input types

##### Key Insights from README
- Describes the pipeline: markdown → parsed blocks → mapped terms → RDF triples → Turtle serialization
- Mentions example usage and that the model is experimental
- Clarifies that “notes” and “concepts” are distinct RDF entities

##### Main Components and Their Relationships
a. Input Layer
- Vault file discovery (example-vault folder)
- Markdown files fed into indexers
b. Parsing & Indexing
- “indexers/vault.js” reads directory tree
- Breaks files into blocks or headings
c. Triplification Layer
- “astTriplifier.js”: Converts AST nodes to preliminary triples
- “canvasTriplifier.js”: Handles special “.canvas” files
- “knownLinks.js”, “populateData.js”, “populateLink.js”, “specialData.js”: handle different kinds of relationships and metadata
d. Term Mapping
- defaultTermMapper.js: maps text keys (e.g., “schema:image”) to RDF predicates
- defaultCustomMapper.js: user-supplied overrides
e. Post-Processing
- Merges triples, applies namespaces, cleans up blank nodes
- Writes final Turtle or JSON-LD output
f. CLI & Example
- index.js: exposes API for programmatic use
- example.js: shows typical invocation

##### Architectural Patterns & Principles
- Modular pipeline: clear separation between indexing, transformation, mapping, and serialization
- Strategy pattern in triplifiers: each file or block type has its own handler
- Pluggable term mappers for extensibility
- Namespace management for consistent RDF prefixes

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Layer"
        MV["Markdown Vault"]:::store
    end

    subgraph "Indexing"
        I["Vault Indexer"]:::pipeline
    end

    MV -->|"raw text"| I

    subgraph "Parsing & Indexing"
        P["Parser (AST nodes)"]:::pipeline
    end

    I -->|"file blocks"| P

    subgraph "Triplification"
        AT["AST Triplifier"]:::pipeline
        CT["Canvas Triplifier"]:::pipeline
        KL["Known Links"]:::pipeline
        PD["Populate Data"]:::pipeline
        PL["Populate Link"]:::pipeline
        SD["Special Data"]:::pipeline
    end

    P -->|"AST nodes"| AT
    P -->|"AST nodes"| CT
    AT -->|"triples"| KL
    AT -->|"triples"| PD
    AT -->|"triples"| PL
    AT -->|"triples"| SD
    CT -->|"triples"| KL
    CT -->|"triples"| PD
    CT -->|"triples"| PL
    CT -->|"triples"| SD
    KL -->|"raw triples"| TM
    PD -->|"raw triples"| TM
    PL -->|"raw triples"| TM
    SD -->|"raw triples"| TM

    subgraph "Term Mapping"
        TM["Term Mapper"]:::pipeline
    end

    subgraph "Utilities"
        SU["String Utils"]:::config
        UU["URI Utils"]:::config
    end

    SU --> TM
    UU --> TM
    TM -->|"mapped triples"| PP

    subgraph "Post-Processing"
        PP["Post Processor"]:::pipeline
        NS["Namespaces"]:::config
    end

    PP -->|"finalization"| NS
    NS -->|"serialized TTL/JSON-LD"| S

    S["RDF Output"]:::store

    subgraph "CLI & Examples"
        CLI["CLI/API"]:::config
        EX["Example Script"]:::config
        M2R["Markdown-to-RDF"]:::pipeline
        C2R["Canvas-to-RDF"]:::pipeline
    end

    CLI --> I
    EX --> I
    M2R --> I
    C2R --> AT

    %% Click Events
    click I "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/indexers/vault.js"
    click AT "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/triplifiers/astTriplifier.js"
    click CT "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/triplifiers/canvasTriplifier.js"
    click KL "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/triplifiers/knownLinks.js"
    click PD "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/triplifiers/populateData.js"
    click PL "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/triplifiers/populateLink.js"
    click SD "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/triplifiers/specialData.js"
    click TM "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/termMapper/defaultTermMapper.js"
    click TM "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/termMapper/defaultCustomMapper.js"
    click SU "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/strings/string.js"
    click UU "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/strings/uris.js"
    click PP "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/postProcess.js"
    click NS "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/namespaces.js"
    click CLI "https://github.com/cristianvasquez/vault-triplifier/blob/main/index.js"
    click EX "https://github.com/cristianvasquez/vault-triplifier/blob/main/example.js"
    click M2R "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/markdown-to-RDF.js"
    click C2R "https://github.com/cristianvasquez/vault-triplifier/blob/main/src/canvas-to-RDF.js"

    classDef pipeline fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef store fill:#90EE90,stroke:#333,stroke-width:1px
    classDef config fill:#FFD580,stroke:#333,stroke-width:1px
```
