Architecture Overview

fialr is local-only archival infrastructure. Every design decision traces back to seven ordered principles. This page documents those principles, the platform adapter layer, the configuration system, and the two-layer metadata architecture.

Design principles

Ordered by priority. When principles conflict, the higher-ranked principle wins.

#	Principle	Implementation
1	Provenance over convenience	Append-only operation ledger. Original state always recoverable.
2	Content hash as identity	BLAKE3 primary, SHA256 secondary. Filenames and paths are mutable metadata.
3	SQLite as ledger, XATTRs as cache	SQLite is authoritative on every platform. XATTRs are silently omitted where unsupported.
4	Local-only enrichment	Ollama on localhost only. Abstracted behind `inference.py` so cloud endpoints cannot be configured.
5	Safety by default	Dry-run on. Explicit flag to execute. No destructive operation runs without human approval.
6	Schema as versioned document	`schema.yaml` carries a version field. Migrations committed before files move.
7	Portability over lock-in	SQLite, TOML, YAML, standard Python, no proprietary stores.

Platform adapter layer

Core modules never contain platform-specific code. No if sys.platform outside platform/. Core imports from platform/base.py and receives the correct adapter at runtime.

Implemented adapters

Capability	macOS	Linux	Windows
Extended attributes	`com.fialr.*` via `xattr`	`user.fialr.*` via `pyxattr`	NTFS ADS (limited)
Default vault	APFS encrypted sparse bundle	VeraCrypt	VeraCrypt
Sync pause	`brctl pause com.apple.CloudDocs`	N/A	N/A
Status	Implemented	Planned	Planned

macOS is the primary platform. Linux and Windows adapters are defined but not yet fully tested.

Configuration system

fialr uses three configuration files, all in the config/ directory:

File	Format	Purpose
`fialr.toml`	TOML	Primary runtime configuration: hash algorithm, buffer size, checkpoint interval, enrichment model, exclusions, naming rules
`schema.yaml`	YAML	Versioned directory schema: category-to-directory mapping, operational directories, retention policies
`sensitivity.yaml`	YAML	Tier classification rules: path patterns, filename patterns, extensions for each tier

Configuration is loaded by utils/config.py. The fialr config command reads, validates, and modifies fialr.toml.

Key configuration sections

[general]
hash_algorithm = "blake3"
secondary_hash = "sha256"

[inventory]
buffer_size = 262144
checkpoint_interval = 50

[exclusions]
directories = []
patterns = []

[enrichment]
model = "llama3.2"
endpoint = "http://localhost:11434"
confidence_threshold = 0.7

[vault]
path = ""

Two-layer metadata architecture

Metadata is stored in two layers with clear authority:

SQLite (authoritative)

The SQLite database (.fialr/fialr.db) is the source of truth for all metadata and audit history on every platform.

Table	Primary Key	Purpose
`files`	content_hash (BLAKE3)	Canonical record per unique file
`paths`	hash + path	All current and historical paths
`operations`	op_uuid	Append-only audit ledger (non-rebuildable)
`jobs`	job_uuid	Job metadata and config snapshots
`duplicates`	group_id	Duplicate groups with canonical selection
`review_queue`	hash	Files pending human review
`schema_meta`	version	Schema migration history

The operations table is append-only. It is the audit ledger. It is never truncated, never rebuilt, never modified after write.

XATTRs (cache)

Extended attributes are a derived cache layer. They are rebuilt from SQLite, never the reverse.

Attribute	macOS Key	Linux Key
Content hash	`com.fialr.hash`	`user.fialr.hash`
Secondary hash	`com.fialr.hash_sha256`	`user.fialr.hash_sha256`
Sensitivity	`com.fialr.sensitivity`	`user.fialr.sensitivity`
Category	`com.fialr.category`	`user.fialr.category`
Entity	`com.fialr.entity`	`user.fialr.entity`
Tags	`com.fialr.tags`	`user.fialr.tags`
Reviewed	`com.fialr.reviewed`	`user.fialr.reviewed`
Original name	`com.fialr.original_name`	`user.fialr.original_name`
Original path	`com.fialr.original_path`	`user.fialr.original_path`
Job UUID	`com.fialr.job_uuid`	`user.fialr.job_uuid`
Enriched at	`com.fialr.enriched_at`	`user.fialr.enriched_at`
Exclude flag	`com.fialr.exclude`	`user.fialr.exclude`

XATTR degradation policy

When XATTRs are unsupported (FAT32, exFAT, network mounts), fialr writes to SQLite only. The skip is logged. No error is raised. No functionality is lost. The system degrades gracefully because SQLite is always authoritative.