> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pysquirrels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Project structure

> Overview of the file structure in a Squirrels project

When you create a new Squirrels project using the [sqrl new](/references/cli/new) or [sqrl init](/references/cli/init) commands, a standard directory structure is generated. This structure is designed to organize your configuration, models, and resources effectively.

```
my_project/
├── .env (and/or .env.local)
├── squirrels.yml
├── pyconfigs/
|   ├── connections.py
|   ├── parameters.py
|   ├── context.py
|   └── user.py
├── seeds/
├── macros/
├── models/
|   ├── builds/
|   ├── dbviews/
|   ├── federates/
|   └── sources.yml
├── resources/
|   └── public/
└── dashboards/
```

Only the [squirrels.yml][squirrels file] file is required for a Squirrels project. Every other file is optional. See the [sqrl get-file](/references/cli/get-file) command for a quick way to add sample files to your Squirrels project.

## Core configurations

### [squirrels.yml][squirrels file]

The manifest file for your project. It defines the datasets and other project-level settings.

### `.env` or `.env.local`

The environment variables file for your project. Squirrels uses [environment variables][env vars] for specific project configuration that may differ based on the hosted environment.

### `duckdb_init.sql`

The initialization script for DuckDB. A global initialization script can also be specified at `~/.squirrels/duckdb_init.sql`.

## Python configurations

### pyconfigs/

The `pyconfigs/` directory contains Python modules that configure various aspects of your project.

* **`connections.py`**: Defines database connections. You can specify connection strings for different environments or data sources here.
* **`parameters.py`**: Configures parameters that can be used in your models. This includes defining widgets, default values, and validation logic.
* **`context.py`**: Provides a dictionary of variables and functions available to your Jinja templates and Python models. Useful for sharing constants or helper functions.
* **`user.py`**: Defines the user model and authentication logic. You can customize user attributes and how they map to dataset permissions.

## Data model configurations

### models/

The `models/` directory holds the logic for transforming your data.

* **`builds/`**: Contains models that are materialized as tables or views in the database. These are typically executed once during the build process.
* **`dbviews/`**: Dynamic SQL views that are executed on the database at query time. These can use parameters to filter or aggregate data dynamically.
* **`federates/`**: Models that can combine data from multiple sources. These can be SQL queries or Python scripts that return dataframes.
* **`sources.yml`**: A YAML file where you define your source tables and their properties. This helps in documenting and managing dependencies.

### macros/

Custom Jinja macros can be placed here. Macros are reusable snippets of SQL or logic that can be called from your models.

### seeds/

CSV files that contain static data to be loaded into the database. Seeds are useful for lookup tables or small reference datasets.

## Dashboard configurations

### dashboards/

This directory contains dashboard definitions. Dashboards can be defined in YAML or Python and reference the datasets created in your models.

## Resource files

### resources/

The `resources/` directory contains resource files used by your project. For example, non-code files used by the Python configuration files.

### resources/public/

The `resources/public/` directory is a special subdirectory of `resources/` of the Squirrels project. It contains public-facing static assets (images, CSS, JS, etc.) that can be served by the API server. You can access these assets using the `/public` route.

For instance, if you have an image in `resources/public/images/logo.png`, you can access it using the `{mount_path}/public/images/logo.png` route. When running in standalone mode (i.e., using `sqrl run`), the mount path is `/analytics/{project_name}/v{project_version}`.

### target/

Artifacts or outputs generated by Squirrels are stored here. This folder is typically ignored by version control.

* **`compile/`**: Contains the compiled SQL files generated by `sqrl compile`.
* **`duckdb_init.sql`**: Generated initialization script for DuckDB. This is generated from the global initialization script (found at `~/.squirrels/duckdb_init.sql`) followed by line breaks and the project initialization script (found at `my_project/duckdb_init.sql`).
* **`vdl_catalog.duckdb`**: The catalog database for the Virtual Data Lake (VDL). This is a DuckDB database that contains the metadata for the VDL, unless specified otherwise through the `SQRL_VDL__CATALOG_DB_PATH` environment variable.
* **`vdl_data/`**: The data directory for the Virtual Data Lake (VDL). This is a directory that contains the data for the VDL, unless specified otherwise through the `SQRL_VDL__DATA_PATH` environment variable.

[squirrels file]: /project/squirrels-yml

[env vars]: /project/env-vars