# Architecture

How your vault, the app, the loam command line and plugins fit together, and what stays on your disk.

Loam keeps your notes as plain files, and runs everything else from them. The app, the `loam` command line and plugins act on the same vault, through the same commands. This page explains where your data lives and how the parts depend on each other.

## The vault is a folder

A vault is a plain folder. Copy it to another Mac and the whole app comes with it. This is what a vault looks like:

```text
My Vault/
├── notes and folders, any depth      plain Markdown
├── Attachments/                      files dropped or pasted into notes (the folder is a setting)
├── Projects/Projects.base            a collection (Obsidian Bases YAML)
├── .loam/
│   ├── config.json                   enabled plugins, settings, shortcuts, theme
│   ├── plugins/<id>/                 your own plugins: plugin.json and sources
│   ├── themes/<name>.json            theme tokens
│   └── cache/                        disposable: note index, compiled plugins
├── .trash/                           deleted notes, kept for 30 days
└── .git                              only with Git sync
```

Notes are plain Markdown files, so other tools can read them too.

## One set of commands, two front ends

Every feature exposes its actions as commands. The app shows them as buttons, menus and panels. The `loam` command line runs the same commands from a terminal or an agent.

- Commands work without a window. The command line runs them on the vault directly.
- Commands that only make sense in the window, such as the theme commands, run inside the open app with `loam app run`.
- The app watches the vault folder. A change made by a command or an agent shows at once in the open window.
- The app and the command line share one runtime, so the same plugins run in both, as the vault’s config says.

## Plugins

Every feature is a plugin. Some essential plugins ship enabled: the Markdown editor, the file explorer, the quick switcher, search, backlinks, note info and the calendar of daily notes.

- Each essential plugin can be replaced by another that offers the same service, or turned off. The rest of the app keeps working.
- Plugins use named contracts and never depend on each other directly. A plugin that needs an optional service works without it.
- Turning off a plugin also turns off the plugins that need it. The plugin manager lists them before it confirms.
- A plugin from your vault lives in `.loam/plugins/<id>/`. It is off by default, and it starts only when the vault’s config enables it.
- Holding Option at launch opens the vault in safe mode. Safe mode uses a short list of plugins, and never loads a plugin from the vault.

## What stays on disk

- **Notes, folders, attachments and collections** are plain files in the vault.
- **`.loam/config.json`** holds the enabled plugins, their settings, shortcuts, theme and “Open with” choices. It travels with the vault.
- **`.loam/cache/`** is rebuilt as needed. It is safe to delete, and deleting it loses nothing.
- **Compiled plugins** depend on the Mac, its CPU and its Swift version. They live in the cache and are rebuilt from their sources.
- **The window layout**, with its open tabs and splits, is kept per Mac in the cache. Two Macs that sync one vault do not fight over it.
- **Deleted notes** go to `.trash/`, where they stay for 30 days. A file records the date each one was moved there.
- **Git data**, with Git sync, is in `.git`. In iCloud Drive, keep it outside the vault. See [Git sync](/docs/git-sync).

Deleting `.loam/` loses settings and plugins, but never a note.

## Limits

- Plugins run inside the app, with its access. Their permissions are declared and shown, not enforced. See [Plugin permissions](/docs/permissions).
- Backlinks follow standard Markdown links only, such as `[Beta](Projects/Beta.md)`. `[[wikilinks]]` are shown in the editor, but the note graph does not index them.
- Turning encryption off for Git sync is not supported yet. See [Git sync](/docs/git-sync).