# Concepts

FsPulse is centered around tracking and understanding the state of the file system over time. The core entities in FsPulse — roots, scans, items, and changes — represent a layered model of this information.

---
## Scans

Scans are the units of work performed by FsPulse. A scan is performed on a file system tree specified by
a path. A scan deeply traverses the specified path and its children, recording information on the
files and directories discovered. The details of scanning are explained in [Scanning](scanning.md). 

---

## Root

A **root** is the starting point for a scan. It represents a specific path on the file system that you explicitly tell FsPulse to track.

Each root is stored persistently in the database, and every scan you perform refers back to a root.

- Paths are stored as absolute paths.
- Each root has a unique ID.
- You can scan a root multiple times over time.

---

## Scan

A **scan** is a snapshot of a root directory at a specific point in time.

Each scan records metadata about:
- The time the scan was performed
- Whether hashing and validation were enabled
- The collection of items (files and folders) found during the scan

Scans are always tied to a root via `root_id`, and are ordered chronologically by `started_at`.

---

## Item

An **item** represents a single file or folder discovered during a scan.

Each item includes metadata such as:
- Path
- Whether it's a file or directory
- Last modified date
- Size
- Optional hash and validation info

Items are created when newly seen, and marked with a tombstone (`is_ts = true`) if they were present in previous scans but no longer exist.

---

## Change

A **change** represents a detected difference in an item between the current scan and a previous one.

Changes may reflect:
- File additions
- File deletions
- Metadata or content modifications

Each change is associated with both the scan and the item it affects.

---

## Entity Flow

A simplified representation of how the entities relate:

```text
Root
 └── Scan (per run)
      └── Item (files and folders)
           └── Change (if the item changed)
```

---

These concepts form the foundation of FsPulse’s scan and query capabilities. Understanding them will help you make the most of both interactive and command-line modes.