# Concepts

The data model behind elek.io Core: Projects, Collections, Components, Entries, Values, Assets and Releases, and how they relate.

```
|-- Project - e.g. "Website"
|   |-- Component - e.g. "Author"
|   |   Reusable, named groups of field definitions that can be referenced by Collections.
|   |-- Collection - e.g. "Blog"
|   |   Contains field definitions all Entries and Values of the Collection must follow.
|   |   Can reference Components to reuse shared field definitions.
|   |   |-- Entry - e.g "Post"
|   |   |   |-- Value - e.g for a post's title: "Quarterly results 7% higher than expected"
|   |   |   |-- Asset - a reference to a previously added Asset like image, PDF or ZIP
|   |   |   |-- Entry - a reference to another Entry e.g. to show the user related posts
|   |-- Release - e.g. "v1.0.0" - a tagged snapshot of the Project at a specific point in time
```

## Projects

Are a container for Collections, Components, Entries, Values and Assets. Think of a folder containing all the relevant files. Projects are version controlled with git, so you can roll back to previous versions of files at any time. Change a Project only through Core, never with git or an editor by hand, see [`git-and-sync.md`](https://elek.io/en/documentation/core/git-and-sync#change-a-project-only-through-core).

Each Project declares its supported languages in its settings, along with one of them as the default. Translatable content (admin metadata and Entry Values) is validated against those languages, not the full universe of supported language codes.

## Collections

Contains field definitions (a schema) for possible Values each Entry can or has to have. e.g. for a Blog, it could have the following field definition for each post / Entry:

- an image that is displayed on top of the post (Asset reference), which lets the user pick a jpeg or png from disk
- a title to catch users attention (Value), a single line input that is required and at most 150 characters long
- content that contains multiple headlines and paragraphs (Value), a markdown editor so the text can carry formatting
- an author that wrote the post (Entry reference), which lets the user pick an Entry of another Collection

A definition says more than the type. It also says what the input field looks like and what a Value has to satisfy.

For the full catalogue of field types and their constraints, see [`fields.md`](https://elek.io/en/documentation/core/fields).

## Components

Are reusable, named groups of field definitions that can be referenced by one or more Collections. Instead of duplicating the same field definitions across Collections, you define them once as a Component and reference it through a `dynamic` field. When you update a Component's field definitions, the change propagates to all Collections that use it.

See [Composing with Components](https://elek.io/en/documentation/core/fields#composing-with-components) for a worked example.

## Entries

Contains Values and references that follow the Collection's field definitions. Why references and not the Assets or Entries themself? To make Values reusable for different Entries and even Collections - so when you update an Asset or Entry, it updates everywhere you've referenced it.

## Values

Represent either a single piece of data like the string "How to be successful in 3 easy steps", a number or a boolean - or a reference to Assets or other Entries. Rich body content is stored as a structured markdown abstract syntax tree (mdast) rather than a markdown string. See [`markdown-content.md`](https://elek.io/en/documentation/core/markdown-content).

Direct Values (`string` / `number` / `boolean`), `reference` and `mdast` Values store per-language content. `component` Values store an ordered, language-independent array of items. The full `Value` union lives in `src/schema/valueSchema.ts` and is documented in [`fields.md`](https://elek.io/en/documentation/core/fields#value-structure).

## Assets

Are files / blobs like images (png, jpeg etc.), documents (excel sheets etc.), music or a compressed folder. Assets have two files inside the Project's repository - the actual file and a file containing meta information like the size.

## Releases

Are tagged snapshots of a Project at a specific point in time, managed through git tags. They allow you to mark stable versions of your content that can be deployed or exported.

## See also

- [`fields.md`](https://elek.io/en/documentation/core/fields) - full field type reference and the Value structure
- [`schema-changes.md`](https://elek.io/en/documentation/core/schema-changes) - how editing field definitions cascades into existing Entries
- [`markdown-content.md`](https://elek.io/en/documentation/core/markdown-content) - how rich `markdown` Values are stored and rendered
- [`asset-management.md`](https://elek.io/en/documentation/core/asset-management) - the two-file Asset model, creating, reading and deleting Assets
- [`git-and-sync.md`](https://elek.io/en/documentation/core/git-and-sync) - the branch model and synchronizing with a remote
- [`releases.md`](https://elek.io/en/documentation/core/releases) - tagged snapshots and promoting `draft` into `main`
- [`storage-layout.md`](https://elek.io/en/documentation/core/storage-layout) - where Projects and their files live on disk
- [`error-handling.md`](https://elek.io/en/documentation/core/error-handling) - `CoreError` and validation error patterns