> For the complete documentation index, see [llms.txt](https://xylem.gitbook.io/xylem-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xylem.gitbook.io/xylem-docs/4.-architecture-and-structure/4-architecture/internal-structure.md).

# Internal Structure

Xylem is organized into distinct functional layers that separate memory allocation, hardware devices, database logic, and query compilation.

```
xylem/
├── CMakeLists.txt        # Build system configuration
├── library.json          # PlatformIO library configuration
├── include/
│   └── Xylem/            # Public Headers
└── src/
    └── Xylem/            # Implementation Files
```

***

## Module Layout

### 1. Hardware Abstraction Layer

* `BlockDevice.hpp` / `BlockDevice.cpp`
  * Defines the `BlockDevice` interface and custom read/write hooks. Simulated as POSIX files or memory blocks.
* `Allocator.hpp` / `Allocator.cpp`
  * Handles low-level physical block allocation and reclaiming. Implements wear-leveling algorithms.
  * **Auto-Expansion:** If `deviceExpands = true` is set on the configuration, Xylem can dynamically request external storage growth (e.g. via `ftruncate`) in `4MB` chunks (1024 blocks). This prevents fragmentation and allows databases to start at 0 bytes and cleanly grow forever.
* `Format.hpp`
  * Sets structural layouts, block headers, and geometry boundaries.

### 2. Relational & Schema Core

* `TableStore.hpp` / `TableStore.cpp`
  * Creates tables dynamically from signatures. Handles page management, row insertions, edits, deletions (tombstones), and MVCC snapshots.
  * **Transaction Batching:** Table operations can be wrapped in `xm.lock()` and `xm.unlock()` routines to drastically bundle bulk insertions/mutations inside a single memory snapshot. This minimizes B+Tree traversal and journaling bottlenecks by combining hundreds of operations per physical flush.
* `Cache.hpp` / `Cache.cpp`
  * Maintains a dirty-page cache using an LRU eviction strategy. Flushes modified blocks back to the physical layer.

### 3. BLAKE2b CAS Storage

* `BlobStore.hpp` / `BlobStore.cpp`
  * Manages the Content-Addressable Blob database. Stores files based on their BLAKE2b hashes, keeps reference tracking, and handles garbage collection.

### 4. Search & Vector Core

* `HNSW.hpp` (header-only)
  * Calculates vector graphs and performs Hierarchical Navigable Small World clustering. Executes fast Cosine Similarity lookups.
* `CryptItem.hpp`
  * Handles row-level encryption pipelines using AES/symmetric encryption tools.

### 5. Queries & CLI

* `Query.hpp` / `QueryParser.hpp` / `QueryParser.cpp`
  * Parses incoming query strings into operational pipelines (like `MATCH`, `FOLLOW`, `ASSERT`). Supports comment sanitization (`#` and `//`).
* `Watcher.hpp` / `Watcher.cpp`
  * Tracks query conditional channels, registering pull/push callbacks.
* `Xylem.hpp` / `Xylem.cpp`
  * The top-level orchestrator. Houses `XylemEngine` and integrates all stores and drivers.
* `xy.cpp` (CLI Binary)
  * Interactive terminal application for managing databases, transferring files via `IO`/`OI`, and running queries.