---
name: mprove-project-structure
description: Mprove project files and folders structure patterns
---

# mprove-project-structure

## Connections

Connections are created by user in Mprove Server UI.
If connection name follows recommended `<prefix>_<db-type>` pattern - then reuse this prefix in malloy file names.
If connection name does not follow this pattern - ask user before continue - maybe he will fix it.

## Project Structure

```
my-project/
  mprove.yml                                        # project config
  data/                                             # mprove_dir (set in mprove.yml)
    schemas/                                        # schema files
      c1_postgres.ecommerce.schema                  # <connection>.<schema>.schema
    c1_postgres/                                    # connection folder (one per database connection)
      models/
        tables/                                     # table source files
          c1_orders_tx.malloy                       # <prefix>_<table>_tx.malloy
          c1_users_tx.malloy
          c1_products_tx.malloy
          c1_user_order_facts_tx.malloy             # <prefix>_<derived_name>_tx.malloy - derived table source
        c1_order_items.malloy                       # main model file: <prefix>_<table>.malloy
      charts/
        BSANVXV135J7MF4YX32G.chart                  # <ID>.chart (auto-generated by Mprove UI)
      dashboards/
        TDEXWBE5PI2X17CJCFKC.dashboard              # <ID>.dashboard
      reports/
        IEWZFR718VMKXXIHDV5J.report                 # <ID>.report
    mprove-users/                                   # objects "saved" by users through server UI
      <user-id>/
        AFASVXV135J7MF4Y387D.chart
        FJS29ASDFJLPA7KJ8SDF.report
        JF9L7AK7J9SDF7KL8SJD.dashboard
```

Connection folder names must match the connection name configured in Mprove server.

## mprove.yml

Project configuration file at the repository root.

```yaml
mprove_dir: ./data
case_sensitive_string_filters: false
format_number: ""
thousands_separator: " "
currency_prefix: "$"
currency_suffix: ""
```

- `mprove_dir` - path to the data directory (relative to project root)

## Models

### Table Source Files

Each database table gets its own file in `models/tables/`.

Naming convention: `<prefix>_<table_name>_tx.malloy`

- `<prefix>` matches the connection folder prefix (e.g. `c1`)
- `_tx` suffix indicates a table source definition

Source naming inside the file:

- `<prefix>_<table>_table` - raw table reference (e.g. `c1_orders_table`)
- `<prefix>_<table>_tx` - extended source with primary key, measures, dimensions (e.g. `c1_orders_tx`)

The raw table reference uses `<connection>.table('<schema>.<table>')`.

### Derived Table Sources

A derived table source imports another `_tx` source and produces a new `_tx` source.

File naming follows the same convention: `<prefix>_<derived_name>_tx.malloy`

Import uses relative path within `tables/`:

```
import './c1_orders_tx.malloy';
```

### Main Model Files

Main model files sit directly in `models/` (not in `tables/`).

Naming convention: `<prefix>_<table>.malloy`

A model file:

1. Imports table sources from `./tables/` using relative paths
2. Defines a source marked with `#(mprove) model`
3. Joins table sources together
4. Adds computed measures

Import paths use `./tables/`:

```
import './tables/c1_order_items_tx.malloy';
import './tables/c1_orders_tx.malloy';
import './tables/c1_users_tx.malloy';
```

The model source name (e.g. `c1_order_items`) is what charts, dashboards, and reports reference.

## Naming Conventions Summary

| Item                       | Pattern                        | Example                          |
| -------------------------- | ------------------------------ | -------------------------------- |
| Connection folder          | `<connection_name>`            | `c1_postgres`                    |
| Table source file          | `<prefix>_<table>_tx.malloy`   | `c1_orders_tx.malloy`            |
| Raw table source name      | `<prefix>_<table>_table`       | `c1_orders_table`                |
| Extended table source name | `<prefix>_<table>_tx`          | `c1_orders_tx`                   |
| Model file                 | `<prefix>_<table>.malloy`      | `c1_order_items.malloy`          |
| Model source name          | `<prefix>_<table>`             | `c1_order_items`                 |
| Schema file                | `<connection>.<schema>.schema` | `c1_postgres.ecommerce.schema`   |
| Chart file                 | `<ID>.chart`                   | `BSANVXV135J7MF4YX32G.chart`     |
| Dashboard file             | `<ID>.dashboard`               | `TDEXWBE5PI2X17CJCFKC.dashboard` |
| Report file                | `<ID>.report`                  | `IEWZFR718VMKXXIHDV5J.report`    |