Technical Architecture Guide
This document provides a technical overview of the modular architecture powering this vault viewer. The project has evolved from a monolithic script into a separated, OOP-based application.
1. Orchestration Layer (index.php)
The root index.php acts as a thin bootstrap. It no longer contains logic; instead, it includes the core components in sequence:
inc/header.php: SEO, metadata, and CSS assets.inc/sidebar.php: Navigation tree generation.inc/content.php: Routing and Markdown rendering.inc/footer.php: Modals, JavaScript assets, and closing tags.
2. The Engine (inc/functions.php)
The Vault class is the heart of the application. It encapsulates all file-system operations:
- Tree Building:
Vault::buildTree()recursively scans the vault to generate the sidebar navigation. - Note Metadata:
getNoteDisplayName()extracts titles from YAML frontmatter or H1 tags. - Discovery: Methods like
getRecentAddedFiles(),findBacklinks(), andfindOrphanedNotes()power the knowledge discovery features. - Security:
isFileAdminOnly()and realpath validation ensure path traversal protection.
3. Modular Actions (inc/actions/)
Logic for specific operations is isolated in the inc/actions/ directory to reduce context overhead:
notes.php: Handles saving, renaming, moving, and deleting files.view.php: Handles the AJAX preview engine and Graph View data generation.seo.php: Generates dynamicsitemap.xmlandrss.xmlfeeds.folders.php: Manages directory-level operations (creation/deletion).
4. Markdown Pipeline (inc/plugins/Parsedown.php)
We use a two-pass rendering pipeline:
- Regex Pre-processing: Obsidian-specific syntax is converted to HTML/Clean URLs:
<img src='vault/Image' alt='Image' style='max-width:100%;'>-><img>tags.<a href='/WikiLinks'>WikiLinks</a>-> Internal relative<a>tags.#tags-> Search query links.
- Markdown Conversion: The pre-processed text is passed to
Parsedown::text()for standard Markdown-to-HTML conversion.
5. Frontend State (inc/assets/script.js)
- Persistence: Folder toggle states and theme preferences (Dark/Light/System) are stored in
localStorage. - Interactivity: AJAX-based previewing, Graph View rendering via
vis-network, and keyboard shortcuts (Ctrl+S for saving). - TOC Highlighting: Dynamic Table of Contents generation with scroll-spy functionality.