# Projects

A project is at the core of your Amfelt experience. It connects data sources to your data platform and defines the jobs that load your data.

## Overview

Amfelt uses project files to configure the data sources, the target data platform, and the jobs that load raw data and build its history and bridge layers. Project files use the YAML (Yet Another Markup Language) format, and Amfelt validates them against a JSON Schema ([draft 2020-12](https://json-schema.org/draft/2020-12)). The [project file format reference](/docs/reference/project/) is the full specification of this Project Configuration File (PCF), generated from the released schema.

You can initialize a new project with `amfelt init`.

### Core Elements

A project file is one document: a handful of identity and policy fields at the top, then three collections (sources, targets, and jobs), optional blocks for generated output, and the plugins that serve them. Click on each for a brief explanation.

  ### Identity

Every project declares its `kind` and `apiVersion`, plus a `name`, `version`, and `status`. The `id` is a unique identifier created for you during initialization. A `description` and a `createdAt` timestamp are optional.

  ### Environment and policy

A project belongs to one `environment`, and `allowCrossEnvironment` controls whether a job may combine sources and targets from different environments. `maxTargetConnections` caps concurrent connections to the target. `driftPolicy` declares what should happen when a source schema changes: a separate action for a `patch`, `minor`, or `major` change, with overrides per source, and per object or column where a single table needs different handling. Changes are classified and surfaced today; applying the policy automatically at run time is on the roadmap.

  ### Sources

Sources refer to a data source such as a database or a file (API sources are on the roadmap). Amfelt uses data contracts to formally define the structure, ownership, and data quality expectations of data sources. Connection details live in the data contract or in the source's own `server`, which takes precedence. Credentials stay out of both: `secretRef` points to them in a vault.

  ### Targets

Targets are the data platforms you synchronize into, such as PostgreSQL or DuckDB. File-based destinations, such as Parquet files in an object store, are on the roadmap. A target names the plugin that writes to it, its `server` connection details, a `secretRef` for credentials, and an optional `maxConnections` cap.

  ### Jobs

Jobs move data between a named source and target. Each job selects objects from the source contract with a glob, names the data platform `layer` it populates (`staging`, `history`, `bridge`, `business`, or `all`). A job can record a `writeMode`, but no run acts on it yet: staging is reloaded in full every time. `historyMode` decides what the history layer keeps, and unlike `writeMode` it can be overridden per object (see [write modes and history](/docs/concepts/write-modes-and-history/)). The target connector builds the history and bridge layers for each job, and the bridge layer may use business-friendly names to aid downstream data consumers. Scheduling belongs to the job: its `runs` are the strategy-and-schedule pairs that execute the selection (`full` ships today; `incremental` and `cdc` are on the roadmap), and `maxParallel` bounds how many objects it processes at once. A column can be excluded per object with `columns.extract`, so a sync does not select, stage, or historize it, or create it in the target. Primary-key, cursor, and event-time columns cannot be excluded, and an advise run still profiles every column of the tables it discovers. That is exclusion rather than protection. Amfelt does not mask, encrypt, or tokenize the values it does load; those are on the roadmap.

  ### Generated output

Three optional blocks generate files into the project repository: `docs` for Markdown documentation, `dbt` for a dbt project, and `sql` for the generated SQL. All three are off by default, and each lets you choose its directory.

  ### Plugins

Plugins declare which connector implementations the project uses and at what version, grouped by the role they play: `source`, `target`, and `transformer`. Selecting plugins per category is what makes the platform composable. The `transformer` role and the top-level `transformers` collection are [reserved](/docs/concepts/plugins/): the format accepts them, but no transformer plugin ships today.