# 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:
1. `inc/header.php`: SEO, metadata, and CSS assets.
2. `inc/sidebar.php`: Navigation tree generation.
3. `inc/content.php`: Routing and Markdown rendering.
4. `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()`, and `findOrphanedNotes()` 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 dynamic `sitemap.xml` and `rss.xml` feeds.
- `folders.php`: Manages directory-level operations (creation/deletion).

## 4. Markdown Pipeline (`inc/plugins/Parsedown.php`)

We use a two-pass rendering pipeline:
1. **Regex Pre-processing**: Obsidian-specific syntax is converted to HTML/Clean URLs:
    - `![[Image]]` -> `<img>` tags.
    - `[[WikiLinks]]` -> Internal relative `<a>` tags.
    - `#tags` -> Search query links.
2. **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.

[[docs/docs]]