# chakradharsai5/my-notes architecture

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

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

## Overview

#### Purpose and Entry Points
This repository is a Quartz v4 digital-garden site: it converts the owner’s Obsidian-compatible Markdown vault into a static website. The primary source of truth is `content/`; the root note is `content/index.md`. Build/runtime configuration enters through `quartz.config.ts` and layout composition through `quartz.layout.ts`. The CLI/bootstrap layer starts the build pipeline from `quartz/bootstrap-cli.mjs` and `quartz/build.ts`.

#### Content Domain and Boundaries
The repository is content-heavy rather than application-heavy. Markdown notes, attachments, Excalidraw artifacts, and PDFs are stored together under `content/`, including the main knowledge base at `content/1 Knowledge Hub`, journals at `content/2 Time Capsule`, and authoring templates/assets at `content/Obsidian Functional Stuff`.
Quartz treats this directory as untrusted author content: parsing, frontmatter interpretation, link resolution, filtering, and output emission occur in the framework boundary rather than in the notes themselves. Notes can use Obsidian conventions and internal links.

#### Build Orchestration
The build is a staged static-site generator:
1. discover and parse source files;
2. apply content transformers;
3. remove excluded/draft content through filters;
4. emit pages, indexes, assets, and supporting resources.
These stages are implemented by `quartz/processors/parse.ts`, `quartz/processors/filter.ts`, and `quartz/processors/emit.ts`, coordinated by `quartz/build.ts`. `quartz/worker.ts` and `quartz/bootstrap-worker.mjs` support worker-based execution, separating CLI process startup from build work.

#### Content Transformation and Graph Semantics
Transformers normalize Markdown into rendered content and metadata. Architecturally important transformations include frontmatter parsing, Obsidian-flavored Markdown/wikilinks, link crawling, descriptions, syntax highlighting, and table-of-contents generation. Their registrations and shared contracts live in `quartz/plugins/transformers/index.ts` and `quartz/plugins/types.ts`; examples include `quartz/plugins/transformers/ofm.ts`, `quartz/plugins/transformers/links.ts`, and `quartz/plugins/transformers/frontmatter.ts`.
Resolved links and content metadata drive backlinks, graph view, folder/tag listings, search indexing, aliases, and page routes.

#### Page Rendering and UI Composition
Quartz renders static HTML/JS/CSS using TypeScript and TSX components. Page-level rendering is centered on `quartz/components/renderPage.tsx`, with page variants in `quartz/components/pages/Content.tsx`, `quartz/components/pages/FolderContent.tsx`, and `quartz/components/pages/TagContent.tsx`. The configured layout selects reusable UI components such as navigation, search, backlinks, graph, and explorer from `quartz/components/`.
Client-side enhancements are isolated as inline scripts—for example `quartz/components/scripts/search.inline.ts`, `quartz/components/scripts/graph.inline.ts`, and `quartz/components/scripts/spa.inline.ts`—rather than requiring an application server.

#### Output Emission
Emitters materialize the processed content into static-site artifacts: per-note pages, folder/tag pages, content indexes/search data, aliases, static assets, resource bundles, 404 pages, and optional social images. Core emitters are under `quartz/plugins/emitters/`, especially `contentPage.tsx`, `contentIndex.tsx`, and `componentResources.ts`. This is the main boundary from internal Quartz `FilePath`/vfile representations to deployable files.

#### Runtime, Delivery, and External Services
The project runs on Node.js (version pinned by `.node-version`) with npm dependency management (`package.json`, `package-lock.json`) and TypeScript. It can be containerized through `Dockerfile`. GitHub Actions provides CI, previews, deployment, Docker image build/push, and synchronization workflows under `.github/workflows/`, including `ci.yaml`, `deploy.yml`, and `deploy-preview.yaml`. No database or backend API is represented; deployment serves generated static assets. A Giscus styling asset exists at `quartz/static/giscus`, indicating optional GitHub Discussions-based comments support.

Main entry points: [`quartz/build.ts`](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/build.ts) (Build coordinator), [`quartz/plugins/emitters/contentPage.tsx`](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/plugins/emitters/contentPage.tsx) (Artifact emitters), [`quartz/components/renderPage.tsx`](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/components/renderPage.tsx) (Page renderer), [`quartz/plugins/transformers/index.ts`](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/plugins/transformers/index.ts) (Content transformers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Vault Source"]
  node_vault["Content vault<br/>Markdown vault"]
  node_root_note["Root note<br/>Markdown entry<br/>[index.md]"]
  node_knowledge_hub["Knowledge Hub<br/>note collection"]
  node_time_capsule["Time Capsule<br/>journal collection"]
  node_authoring_assets["Obsidian assets<br/>templates and assets"]
end

subgraph group_build["Quartz Build"]
  node_config["Quartz config<br/>build configuration<br/>[quartz.config.ts]"]
  node_cli["CLI bootstrap<br/>Node entry point<br/>[bootstrap-cli.mjs]"]
  node_worker["Worker runtime<br/>build worker<br/>[worker.ts]"]
  node_build{{"Build coordinator<br/>pipeline orchestrator<br/>[build.ts]"}}
  node_parse["Parse sources<br/>pipeline stage<br/>[parse.ts]"]
  node_transformers["Content transformers<br/>plugin registry<br/>[index.ts]"]
  node_filter["Filter content<br/>pipeline stage<br/>[filter.ts]"]
  node_emit["Emit artifacts<br/>pipeline stage<br/>[emit.ts]"]
  node_emitters["Artifact emitters<br/>output plugins<br/>[contentPage.tsx]"]
end

subgraph group_presentation["Rendering"]
  node_layout["Layout config<br/>UI composition<br/>[quartz.layout.ts]"]
  node_page_renderer["Page renderer<br/>TSX renderer<br/>[renderPage.tsx]"]
  node_page_variants["Page variants<br/>TSX pages<br/>[Content.tsx]"]
  node_client_scripts["Client enhancements<br/>inline scripts<br/>[search.inline.ts]"]
end

subgraph group_delivery["Delivery"]
  node_static_site["Static site output<br/>deployable files"]
  node_github_actions["GitHub Actions<br/>CI and deployment"]
  node_giscus["Giscus styling<br/>comment integration asset"]
end

node_root_note -->|"belongs to"| node_vault
node_knowledge_hub -->|"belongs to"| node_vault
node_time_capsule -->|"belongs to"| node_vault
node_authoring_assets -->|"belongs to"| node_vault
node_cli -->|"starts"| node_build
node_cli -->|"boots"| node_worker
node_config -.->|"configures"| node_build
node_vault -->|"source files"| node_parse
node_build -->|"coordinates"| node_parse
node_parse -->|"parsed content"| node_transformers
node_transformers -->|"normalized content and links"| node_filter
node_filter -->|"publishable content"| node_emit
node_build -->|"coordinates"| node_emit
node_layout -->|"selects components"| node_page_renderer
node_page_variants -->|"defines page forms"| node_page_renderer
node_transformers -->|"rendered content and metadata"| node_page_renderer
node_page_renderer -->|"page output"| node_emitters
node_emit -->|"runs"| node_emitters
node_client_scripts -->|"bundled resources"| node_emitters
node_emitters -->|"writes"| node_static_site
node_github_actions -->|"builds and deploys"| node_static_site
node_giscus -.->|"optional comment styling"| node_static_site

click node_root_note "https://github.com/chakradharsai5/my-notes/blob/v4/content/index.md"
click node_knowledge_hub "https://github.com/chakradharsai5/my-notes/tree/v4/content/1%20Knowledge%20Hub"
click node_time_capsule "https://github.com/chakradharsai5/my-notes/tree/v4/content/2%20Time%20Capsule"
click node_authoring_assets "https://github.com/chakradharsai5/my-notes/tree/v4/content/Obsidian%20Functional%20Stuff"
click node_config "https://github.com/chakradharsai5/my-notes/blob/v4/quartz.config.ts"
click node_layout "https://github.com/chakradharsai5/my-notes/blob/v4/quartz.layout.ts"
click node_cli "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/bootstrap-cli.mjs"
click node_worker "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/worker.ts"
click node_build "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/build.ts"
click node_parse "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/processors/parse.ts"
click node_transformers "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/plugins/transformers/index.ts"
click node_filter "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/processors/filter.ts"
click node_emit "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/processors/emit.ts"
click node_page_renderer "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/components/renderPage.tsx"
click node_page_variants "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/components/pages/Content.tsx"
click node_client_scripts "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/components/scripts/search.inline.ts"
click node_emitters "https://github.com/chakradharsai5/my-notes/blob/v4/quartz/plugins/emitters/contentPage.tsx"
click node_giscus "https://github.com/chakradharsai5/my-notes/tree/v4/quartz/static/giscus"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_vault,node_root_note,node_knowledge_hub,node_time_capsule,node_authoring_assets toneBlue
class node_config,node_cli,node_worker,node_build,node_parse,node_transformers,node_filter,node_emit,node_emitters toneAmber
class node_layout,node_page_renderer,node_page_variants,node_client_scripts toneMint
class node_static_site,node_github_actions,node_giscus toneRose
```

## Components

### Vault Source

Owner-authored Obsidian-compatible content.

- **Content vault**: Markdown vault · Untrusted author content, attachments, and artifacts.
- [Root note](https://github.com/chakradharsai5/my-notes/blob/v4/content/index.md): Markdown entry · `content/index.md`
- [Knowledge Hub](https://github.com/chakradharsai5/my-notes/tree/v4/content/1%20Knowledge%20Hub): note collection · `content/1 Knowledge Hub`
- [Time Capsule](https://github.com/chakradharsai5/my-notes/tree/v4/content/2%20Time%20Capsule): journal collection · `content/2 Time Capsule`
- [Obsidian assets](https://github.com/chakradharsai5/my-notes/tree/v4/content/Obsidian%20Functional%20Stuff): templates and assets · `content/Obsidian Functional Stuff`

### Quartz Build

Staged static-site generation pipeline.

- [Quartz config](https://github.com/chakradharsai5/my-notes/blob/v4/quartz.config.ts): build configuration · `quartz.config.ts`
- [CLI bootstrap](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/bootstrap-cli.mjs): Node entry point · `quartz/bootstrap-cli.mjs`
- [Worker runtime](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/worker.ts): build worker · Separates process startup from build work. · `quartz/worker.ts`
- [Build coordinator](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/build.ts): pipeline orchestrator · `quartz/build.ts`
- [Parse sources](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/processors/parse.ts): pipeline stage · Discovers files and produces Quartz file representations. · `quartz/processors/parse.ts`
- [Content transformers](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/plugins/transformers/index.ts): plugin registry · Registers frontmatter, Obsidian Markdown, links, descriptions, highlighting, and TOC transforms. · `quartz/plugins/transformers/index.ts`
- [Filter content](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/processors/filter.ts): pipeline stage · Removes excluded and draft content. · `quartz/processors/filter.ts`
- [Emit artifacts](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/processors/emit.ts): pipeline stage · Materializes pages, indexes, assets, and resources. · `quartz/processors/emit.ts`
- [Artifact emitters](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/plugins/emitters/contentPage.tsx): output plugins · Produces note pages, indexes, resources, aliases, and static assets. · `quartz/plugins/emitters/contentPage.tsx`

### Rendering

Static page and client enhancement composition.

- [Layout config](https://github.com/chakradharsai5/my-notes/blob/v4/quartz.layout.ts): UI composition · `quartz.layout.ts`
- [Page renderer](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/components/renderPage.tsx): TSX renderer · `quartz/components/renderPage.tsx`
- [Page variants](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/components/pages/Content.tsx): TSX pages · Content, folder, and tag page variants. · `quartz/components/pages/Content.tsx`
- [Client enhancements](https://github.com/chakradharsai5/my-notes/blob/v4/quartz/components/scripts/search.inline.ts): inline scripts · Search, graph, and SPA behavior run in generated pages. · `quartz/components/scripts/search.inline.ts`

### Delivery

Generated site deployment and optional hosted integrations.

- **Static site output**: deployable files · No application server or database is required.
- **GitHub Actions**: CI and deployment · Runs CI, previews, deployment, image workflows, and synchronization.
- [Giscus styling](https://github.com/chakradharsai5/my-notes/tree/v4/quartz/static/giscus): comment integration asset · Supports optional GitHub Discussions comments. · `quartz/static/giscus`

## Connections

- Root note → Content vault: belongs to
- Knowledge Hub → Content vault: belongs to
- Time Capsule → Content vault: belongs to
- Obsidian assets → Content vault: belongs to
- CLI bootstrap → Build coordinator: starts
- CLI bootstrap → Worker runtime: boots
- Quartz config → Build coordinator: configures
- Content vault → Parse sources: source files
- Build coordinator → Parse sources: coordinates
- Parse sources → Content transformers: parsed content
- Content transformers → Filter content: normalized content and links
- Filter content → Emit artifacts: publishable content
- Build coordinator → Emit artifacts: coordinates
- Layout config → Page renderer: selects components
- Page variants → Page renderer: defines page forms
- Content transformers → Page renderer: rendered content and metadata
- Page renderer → Artifact emitters: page output
- Emit artifacts → Artifact emitters: runs
- Client enhancements → Artifact emitters: bundled resources
- Artifact emitters → Static site output: writes
- GitHub Actions → Static site output: builds and deploys
- Giscus styling → Static site output: optional comment styling