# Projects and emolysis.yml

> The Emolysis project folder: models, pipelines, tests, the emolysis.yml project file and the local lakehouse for samples.

An Emolysis project is a plain folder that you own. It holds your models, your pipelines, their tests and one project file. It lives in your own Git repository, next to the rest of your code. Nothing in it is locked to the desktop app: the same folder works from the app, the `emo` command line and an editor or coding agent that supports MCP.

## Creating a project

`emo init <name>` creates the folder, or choose New project in the app. You can also run it inside an existing repository to add a project there.

```sh
emo init orders
```

## Layout

```tree
orders/
  emolysis.yml        project file: name and target platform
  models/             transformations, one per file
  pipelines/          pipelines built from templates, tagged with their platform
  tests/              golden test fixtures and expected outputs
  .emolysis/          local state, not meant to be committed
    lake/             the project's local lakehouse: samples and test tables
```

| Path           | Holds                                                   | Commit it?                   |
| -------------- | ------------------------------------------------------- | ---------------------------- |
| `emolysis.yml` | The project name and its target platform                | Yes                          |
| `models/`      | One transformation per file                             | Yes                          |
| `pipelines/`   | Filled templates, each tagged with platform and profile | Yes                          |
| `tests/`       | Golden test fixtures and expected outputs               | Yes, and keep them synthetic |
| `.emolysis/`   | Local state, including the local lakehouse in `lake/`   | No; add it to `.gitignore`   |

## The project file

`emolysis.yml` names the project and its target platform. The example shows only the fields that are decided.

```yaml
# emolysis.yml (illustrative; the format may change before release)
name: orders
platform: databricks
```

`platform` takes one of `databricks`, `snowflake` or `fabric`. It decides which [platform profile](https://emolysis.com/docs/platform-profiles) the agent loads and which templates it offers. A project targets one platform at a time. Moving to another is an explicit step; see [Deploying](https://emolysis.com/docs/deploying).

## Models and pipelines

A model is a single transformation, usually one SQL select that produces one table. A pipeline is a filled template for one of the ten [shapes](https://emolysis.com/docs/shapes), plus the models it uses.

```sql
-- models/orders_by_month.sql (illustrative)
select
  date_trunc('month', order_date) as month,
  region,
  sum(amount) as revenue,
  count(*) as orders
from orders_clean
group by 1, 2
```

Every generated file is tagged with the platform and the profile version it was written for, so it cannot be deployed to a different platform by accident. The tag travels with the file, so a pull request reviewer can see at a glance what a change targets.

## Tests

`tests/` holds the golden test fixtures for your pipelines: input data and the output you expect, usually small Parquet files. They are committed with the code, so the same tests run on your machine and in pull request checks. Keep fixtures synthetic. See [Golden tests on DuckDB](https://emolysis.com/docs/golden-tests).

## The local lakehouse

`.emolysis/lake/` holds the samples you pull from your platform and the tables DuckDB writes during tests. It is a development copy, not a replacement for your platform's catalog, and it is not meant to be committed. Keep `.emolysis/` in `.gitignore`.

```text
# .gitignore
.emolysis/
```

## What is never in a project

Credentials. Platform tokens and model keys are kept in your machine's credential store, never in `emolysis.yml` or any other project file. Fixtures and models are your files and contain whatever you put in them, so keep real data and secrets out of them.

## Working with Git

`emo sync` and `emo pr`, which commit and push or open a pull request, are planned conveniences; your own Git workflow works just as well. If your team reviews pipeline changes in pull requests, `emo check` in your CI lints, tests and prices each change before it merges; see [GitHub checks](https://emolysis.com/docs/github-checks).

## Status

The layout and the project file can change before the first release. The folder names above, the `platform` field and the rule that credentials stay out of the project are fixed.

---

Page: https://emolysis.com/docs/projects. Emolysis is a product of Bandpey GmbH, Munich, Germany. It is in private development, and nothing is released yet.