# adielbm/notes architecture

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

- Interactive diagram: https://gitdiagram.com/adielbm/notes
- Repository: https://github.com/adielbm/notes

## Overview

##### Main Components
- Content Repository: The “notes” folder contains all the markdown files (notes written in Obsidian format), which serve as the primary content source.
- Quartz Engine: This is the core of the static site generator. It consists of:
– CLI & Build System: Files like quartz/build.ts, quartz/cli (with its submodules) and quartz.config.ts/quartz.layout.ts are responsible for invoking the build process and applying configuration.
– Processors: Under quartz/processors (e.g., emit.ts, filter.ts, parse.ts). They read and transform markdown content.
– Plugins: These include “emitters”, “filters”, and “transformers” (in quartz/plugins and its subdirectories). They perform tasks such as generating content pages, injecting metadata, applying syntax highlighting, managing TOC generation, and more.
– Static Assets: The quartz/static directory contains supporting scripts (script.js), styles (tikz.css, tikzjax.js), and custom SCSS files for styling.
– Utilities & Internationalization: In quartz/util and quartz/i18n, you have shared utility functions, language support (locales), and other helper modules.

##### Detail the Relationships and Interactions
- The build process (invoked via CLI command “npx quartz build -d notes”) first reads configuration files (quartz.config.ts, quartz.layout.ts) and then scans the “notes” directory to ingest markdown content.
- The Processors are then triggered, sequentially parsing the markdown into an intermediate representation, applying filters and transformers via the plugin system (e.g., for citations, frontmatter, GitHub Flavored Markdown, LaTeX, and more).
- Processed content then flows to the Component layer, where React components are rendered to produce the final web pages.
- The generated site, along with static assets, is compiled into a “public” directory ready to be deployed (as indicated by the build and publishing configuration in the README).
- Dockerfile and other configuration files (e.g., tsconfig.json, package.json) facilitate deployment and build management.

##### Architectural Patterns and Design Principles
- Modular Plugin Architecture: Separate concerns by using plugins for transformations, filters, and emitters, which makes the system extensible.
- Separation of Content and Engine: Clear distinction between user-maintained content (“notes” folder) and the site generation logic (Quartz engine).
- Component-based UI Design: Use of React components to build web pages following frontend best practices.
- Build/Deployment Pipeline: Utilization of Node.js, Docker, and CLI scripts to automate the build and deployment process.

##### Relevant Technologies and Frameworks
- Node.js/TypeScript for the backend build logic.
- React (with .tsx components) for rendering the UI.
- SCSS/CSS for styling.
- Docker for containerization (as indicated by the Dockerfile).
- Obsidian (markdown notes format) for content management.
- Several plugins that handle markdown transforms (for citation, syntax, TOC, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Deployment"
        config("Build & Deployment Configuration"):::config
    end

    subgraph "Content Source"
        notes("Content Repository (notes)"):::content
    end

    subgraph "Quartz Engine"
        cli("CLI & Build System"):::cli
        processors("Processors"):::processors
        plugins("Plugins (Emitters,Filters,Transformers)"):::plugins
        ui("UI Components (React)"):::ui
        static("Static Assets"):::static
        utils("Utilities & Internationalization"):::utils
    end

    public["(Public Folder (Output))"]:::output

    %% Relationships and Data Flow
    config -->|"configuration"| cli
    cli -->|"scans for markdown"| notes
    cli -->|"initiates processing"| processors
    processors -->|"transformed content"| plugins
    plugins -->|"injects content"| ui
    cli -->|"integrates assets"| static
    cli -->|"loads helpers"| utils
    static -->|"resources"| ui
    utils -->|"helper data"| ui
    ui -->|"renders pages"| public

    %% Click Events
    click notes "https://github.com/adielbm/notes/tree/main/notes/"
    click cli "https://github.com/adielbm/notes/blob/main/quartz/build.ts"
    click cli "https://github.com/adielbm/notes/tree/main/quartz/cli/"
    click cli "https://github.com/adielbm/notes/blob/main/quartz.config.ts"
    click cli "https://github.com/adielbm/notes/blob/main/quartz.layout.ts"
    click processors "https://github.com/adielbm/notes/tree/main/quartz/processors/"
    click plugins "https://github.com/adielbm/notes/tree/main/quartz/plugins/"
    click ui "https://github.com/adielbm/notes/tree/main/quartz/components/"
    click static "https://github.com/adielbm/notes/tree/main/quartz/static/"
    click utils "https://github.com/adielbm/notes/tree/main/quartz/util/"
    click utils "https://github.com/adielbm/notes/tree/main/quartz/i18n/"
    click config "https://github.com/adielbm/notes/tree/main/Dockerfile"
    click config "https://github.com/adielbm/notes/blob/main/package.json"
    click config "https://github.com/adielbm/notes/blob/main/tsconfig.json"

    %% Class Definitions for Colors and Styles
    classDef cli fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef content fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef processors fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef plugins fill:#ffebcc,stroke:#cc6600,stroke-width:2px;
    classDef ui fill:#cce5ff,stroke:#3366cc,stroke-width:2px;
    classDef static fill:#e6ccff,stroke:#9933cc,stroke-width:2px;
    classDef utils fill:#d9d9d9,stroke:#666666,stroke-width:2px;
    classDef config fill:#ccffff,stroke:#009999,stroke-width:2px;
    classDef output fill:#ffccff,stroke:#990099,stroke-width:2px;
```
