Architecture Overview

fialr is archival infrastructure designed for local-first operation. Every design decision traces back to seven ordered principles. This page documents those principles, the module architecture, 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	Tier-gated enrichment	All tiers use local AI (Ollama) by default. Tier 1 cloud requires two-step confirmation (config flag + CLI flag). Tiers 2-3 support opt-in cloud (Claude API, BYOK) via `fialr config ai`.
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.

Processing pipeline

fialr processes files through a staged pipeline. Each stage can run independently or as part of a combined operation.

Stage	Purpose	Writes to disk
Scan	Traverse filesystem, compute content hashes, build manifest	No (read-only)
Classify	Assign sensitivity tier and category to each file	No (metadata to SQLite)
Plan	Generate proposed moves and renames based on schema and naming convention	No (plan.csv output)
Execute	Apply the reviewed plan: move, rename, set XATTRs	Yes
Enrich	Extract text, run LLM inference, generate metadata and embeddings	Yes (metadata to SQLite)
Deduplicate	Identify exact and near-duplicate files, move copies to staging	Yes

Supporting capabilities run across stages: full-text search (FTS5), semantic search (vector embeddings), encrypted vault storage, integrity validation, undo/rollback, and sidecar export.

All stages produce structured job artifacts (manifest, plan, log, report, checkpoint) for auditability and resumability. Every file operation is logged before and after execution with BLAKE3 hash verification.

Platform adapter layer

Capability	macOS	Linux
Extended attributes	`com.fialr.*` via `xattr`	`user.fialr.*` via `os.getxattr`/`os.setxattr` (stdlib)
Default vault	APFS encrypted sparse bundle (zero install)	age (one-command install)
MIME detection	`python-magic` with `mimetypes` fallback	`python-magic` with `mimetypes` fallback
Machine fingerprint	BLAKE3 hash of `IOPlatformUUID` via `ioreg`	BLAKE3 hash of `/etc/machine-id`
iCloud sync pause	`brctl pause com.apple.CloudDocs`	N/A

The platform check runs in platform/base.py::get_adapter() only. All core modules receive the adapter via dependency injection.

Configuration system

fialr uses three configuration files:

File	Format	Purpose
`fialr.toml`	TOML	Primary runtime configuration: enrichment provider/model, naming rules, exclusions, vault backend, embeddings
`schema.yaml`	YAML	Versioned directory schema: category-to-directory mapping, naming pattern overrides
`sensitivity.yaml`	YAML	Tier classification rules: path patterns, filename patterns, extensions for each tier

Configuration is loaded by the config module. 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]
provider = "ollama"           # "ollama" | "claude" | "two-step"
model = "llama3.2"
cloud_model = "claude-sonnet-4-20250514"
endpoint = "http://localhost:11434"
confidence_threshold = 0.7

[naming]
pattern = "{{ date }}-{{ entity | slugify }}-{{ descriptor | slugify }}.{{ ext | lower }}"
separator = "-"
word_separator = "_"
case = "lower"

[vault]
path = ""
backend = ""                  # "apfs" | "age" | "veracrypt" — empty = platform default

[embeddings]
enabled = true
model = "nomic-embed-text"
dimensions = 768

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
`vault_entries`	hash + vault_path	Files archived in encrypted vaults
`embeddings`	hash + model	Vector embeddings for semantic search and enrichment context
`search_index`	(FTS5 virtual)	Full-text search across file metadata
`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.