Core concepts#

Status: work in progress. A deliberately abstract sketch. These concepts are not about katalyst specifically; katalyst is one instantiation among many. Expect revisions until they settle.

The vocabulary katalyst reasons in, general enough to describe a Postgres table, a directory of markdown files, and a MongoDB collection the same way, so the abstractions built on top bridge them too. Each term’s canonical definition lives in the glossary; this page introduces the concepts and how they fit. For the katalyst-specific instantiation, see the domain model.

The concepts#

• Project is the whole workspace katalyst operates over: a configured root that binds one or more storage backends into named collections. Its configuration is the Config (katalyst’s is the .katalyst/ directory); the collections, items, checks, and inspectors below all live within a project. It is the scope an empty selector addresses.
• Storage is a backend that holds data: a filesystem, a SQLite database, a Postgres instance, an S3 bucket. Katalyst’s realization is the storage layer.
• Collection is a group of items sharing structure: a directory of similar files, a relational table, a Mongo collection. See collections.
• Item is one unit of data in a collection: a markdown file, a table row, a Mongo document.
• Attribute is a named characteristic of an item: a column, a frontmatter key, a response field, even its name or path. A key in a structured object specifically is a field.
• Operation is something storage lets you do with its data: read, list, aggregate, write, and eventually query. Which operations a backend supports is the subject of progressive operations.
• Check asserts a condition on an item or its attributes and reports a violation when it fails. See checks.
• Inspector is the descriptive dual of a check: it measures a distribution and returns evidence, never a verdict. See inspectors.

The same vocabulary across backends#

An operation defined once in this vocabulary, check an attribute, aggregate over a collection, applies to every backend that supports it. Which operations a backend supports, and the structural commitments each demands, is the progressive operations story.