> For the complete documentation index, see [llms.txt](https://codifi-fdm.gitbook.io/codifi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codifi-fdm.gitbook.io/codifi-docs/web-app/composition-builder.md).

# Composition Builder

The Composition Builder is where you design the **data structure** for a Project: the kinds of Records crews can create (archetypes), the fields on each one, how Records relate to each other, and what Project-level information sits above all of it.

Compositions are the answer to "what does a Project look like in Codifi?" A single Composition like *Texas Phase I v2* might define:

* A **Site** Record with 80 fields and a polygon location.
* A **Feature** Record nested under Site.
* A **Shovel Test Probe** Record nested under Site, with a repeater for soil horizons.
* A **Project Details** Record holding the Project-wide metadata (Project name, location, dates, principal investigator).

Build the Composition once, and every Project that uses it inherits the same structure.

***

## The mental model

Five concepts you'll encounter constantly:

| Concept                                                                                   | What it is                                                                                                          |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [**Library**](/codifi-docs/web-app/composition-builder/library.md)                        | Your organization's shared catalog of reusable building blocks (archetypes, fields, value lists, status workflows). |
| [**Archetype**](/codifi-docs/web-app/composition-builder/archetypes-and-relationships.md) | The template for a kind of Record — e.g., "Shovel Test Probe" or "Site." Defines fields, geometry, media policy.    |
| [**Field**](/codifi-docs/web-app/composition-builder/fields-and-field-types.md)           | A single piece of data inside an archetype — text, number, date, dropdown, etc.                                     |
| [**Project Details (PD)**](/codifi-docs/web-app/composition-builder/project-details.md)   | A special, one-per-Project archetype that holds Project-level info (Project name, dates, PI).                       |
| [**Project Template**](/codifi-docs/web-app/composition-builder/project-templates.md)     | The packaged Composition — archetypes wired together with relationships, ready to spawn new Projects.               |

```
Library  →  Project Template  →  Project  →  Records
  (reusable parts)   (the blueprint)   (an instance)   (real data)
```

***

## What's in this section

| Page                                                                                                       | Use it when you want to…                                                                |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [**The Library**](/codifi-docs/web-app/composition-builder/library.md)                                     | Understand how the shared catalog is organized; when to clone vs share library entities |
| [**Archetypes & Relationships**](/codifi-docs/web-app/composition-builder/archetypes-and-relationships.md) | Design the Record types and parent-child relationships for a Composition                |
| [**Fields & Field Types**](/codifi-docs/web-app/composition-builder/fields-and-field-types.md)             | Pick the right field type, configure attributes, understand validation                  |
| [**Project Details**](/codifi-docs/web-app/composition-builder/project-details.md)                         | Set up Project-level metadata that flows into every Record                              |
| [**Project Templates**](/codifi-docs/web-app/composition-builder/project-templates.md)                     | Package a Composition into a publishable template; understand the snapshot model        |

***

## Who builds Compositions?

Composition authoring is gated by the **Composer** role in [RBAC](/codifi-docs/cross-platform-features/roles-based-access-controls-rbac.md). Composer is the only non-admin role with edit access to the Library — so granting it means trusting someone to edit shared data structures used across many Projects.

If you're building Compositions for archaeology, environmental, cultural resource management, or similar work, you'll typically be:

* Building one Composition per state/agency requirement (TX SHPO, UT archaeology, etc.) and reusing it across multiple Projects.
* Cloning an existing Composition when a Project has special needs, and modifying the copy rather than altering the shared original.
* Working in a **Sandbox tenant** first, then promoting tested Compositions into a **Projects tenant** for live use.

***

## The Composition lifecycle

A typical authoring loop:

1. **Design** — what archetypes does this Project need? What relationships? Sketch the tree first, even on paper.
2. **Author in Sandbox** — build the archetypes, fields, and Project template in your Sandbox tenant. Iterate freely.
3. **Test** — create a Sandbox Project from the template, walk a real workflow on web and mobile, fix issues.
4. **Promote** — when satisfied, copy the Composition into the Projects tenant (or finalize in the original tenant if you don't keep them separate).
5. **Use** — Projects spin up from the template; each Project takes its own snapshot of the template at creation time.
6. **Iterate** — library changes flow to *new* Projects, not existing ones (see [Project Templates](/codifi-docs/web-app/composition-builder/project-templates.md) for the snapshot rule).

***

## Common pitfalls

A few things that consistently surprise new composers:

* **Projects snapshot the template at creation.** Editing a library archetype today does **not** automatically update existing Projects that already use it. See [Project Templates](/codifi-docs/web-app/composition-builder/project-templates.md).
* **Archetype labels are shared across the whole tenant.** Don't prefix archetype names with state codes or Project codes unless you genuinely want every Project to see that prefix. See [Archetypes & Relationships](/codifi-docs/web-app/composition-builder/archetypes-and-relationships.md).
* **Title fields must be SingleLine Text.** The MultiLine field type can't be used as a Record's title. See [Fields & Field Types](/codifi-docs/web-app/composition-builder/fields-and-field-types.md).
* **Project Details must have a date range.** Even if your Project has no real start/end dates, a Project Details Record requires a DateRange-typed field. See [Project Details](/codifi-docs/web-app/composition-builder/project-details.md).
* **Cloning beats editing for shared archetypes.** If a change is specific to one Composition, clone the archetype before editing — otherwise you'll pollute every Composition that uses it. See [The Library](/codifi-docs/web-app/composition-builder/library.md).

***

## Related

* [Ripple](/codifi-docs/cross-platform-features/ripple.md) — the formula engine you'll use to wire calculated fields, visibility rules, and cross-Record lookups into your Composition
* [Calculated Fields](/codifi-docs/cross-platform-features/calculated-fields.md) — the concept page that pairs with the Ripple deep-dive
* [Conditional Visibility](/codifi-docs/cross-platform-features/conditional-visibility.md) — same, for show/hide rules
* [Map Setup & Offline Areas](/codifi-docs/web-app/map-setup-and-offline-areas.md) — the Project's map configuration, which is separate from the Composition