> 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/archetypes-and-relationships.md).

# Archetypes & Relationships

An **archetype** is the template for a kind of Record in your Project — a Site, a Feature, a Shovel Test Probe, an Inspection Point. It defines the fields a Record will have, what kind of geometry it captures (point, line, polygon, or none), what media is allowed, and how it relates to other archetypes.

A **relationship** is a parent-child link between two archetypes. A Site can have many Features; a Feature belongs to one Site. Relationships shape both the data hierarchy and the user experience in the field.

***

## What an archetype defines

| Aspect              | What you configure                                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Name & Label**    | Internal name (unique in the Library) and the user-facing label                                                         |
| **Title field**     | Which field acts as the Record's title (the name shown on cards, in lists, etc.). Must be a **SingleLine Text** field.  |
| **Geometry type**   | `SinglePoint`, `Line`, `Polygon`, or no location                                                                        |
| **Map symbology**   | How the archetype draws on the map (point color, line width, polygon fill, etc.)                                        |
| **Media policy**    | Whether the archetype can have a media gallery; which subtypes are allowed (photo, video, file)                         |
| **Sections**        | Logical groupings of fields within the form (e.g., "Identification," "Description," "Documentation")                    |
| **Fields**          | The actual data inputs — see [Fields & Field Types](/codifi-docs/web-app/composition-builder/fields-and-field-types.md) |
| **Relationships**   | Which archetypes can be parents or children of this one                                                                 |
| **Status workflow** | The lifecycle states this archetype's Records can move through                                                          |

> **Screenshot placeholder:** *The archetype editor in the Library, showing the sections sidebar, the title-field picker, the geometry-type selector, and the fields list.*

***

## Designing the relationship tree

A good Composition has a clear hierarchy. Sketch it before building:

```
Project Details
├── Site
│   ├── Feature
│   │   └── Artifact
│   ├── Shovel Test Probe
│   └── Photo Log Entry
├── Transect
│   └── Shovel Test Probe          ← same archetype, different parent
└── Project Area (polygon)
```

A few patterns to know:

* **Multi-parent archetypes are supported.** A "Shovel Test Probe" can have both "Site" and "Transect" as valid parents. Crews pick which parent applies when they create the Record. (Don't split into "Site STP" and "Transect STP" variants — use multi-parent.)
* **Same archetype can appear in multiple places in the tree.** This is fine and common (artifacts can belong to features, sites, or both).
* **You can cap a parent at one child of a given archetype.** For example: "A Site can have only one Project Polygon child." Set the relationship's cardinality to **One** in the relationship editor.

***

## Geometry types

| Type            | When to use                                                                   | Map behavior                            |
| --------------- | ----------------------------------------------------------------------------- | --------------------------------------- |
| **SinglePoint** | Discrete observations — STP, feature center, photo location                   | One vertex per Record                   |
| **Line**        | Transects, paths, fences, linear features                                     | Ordered series of vertices              |
| **Polygon**     | Sites, parcels, Project areas, features with extent                           | Ordered vertices forming a closed shape |
| **None**        | Records that have no geographic location — Photo Log Entries, Project Details |                                         |

Geometry type is set per-archetype and cannot be changed once Records of that archetype exist in any Project (would orphan their captured geometry).

***

## Title fields

Every archetype must have a **title field** — the one shown as the Record's name on map cards, in the list, in reports, and in cross-Record references.

Rules:

* **Must be a SingleLine Text field.** MultiLine isn't supported as a title.
* **Can be Ripple-computed.** A common pattern: parent archetype is "Transect," child archetype is "Shovel Test," and the STP's title is a Ripple formula combining `{parent.title}` + `_STP_{stp_number}`. This gives unique, hierarchical names without crew effort.
* **Auto-numbering hooks in here.** If your title field name ends in a number, the mobile app auto-increments for sibling Records of the same archetype.

> See [Mobile: Record Auto-Numbering](/codifi-docs/mobile-app/mobile-project-settings/record-auto-numbering.md) for the auto-numbering rules.

***

## Sections

Within an archetype, fields are grouped into **sections**. Sections give the form structure and let you collapse / expand groups in the UI.

Common section patterns:

* **Identification** — title, type, status.
* **Description** — narrative fields.
* **Documentation** — photo log links, references.
* **QA** — required-completion fields, sign-off.
* **Repeaters** — soil horizons, artifact tallies, photo log entries (see [Mobile: Repeaters](/codifi-docs/mobile-app/creating-records/understanding-archetypes-and-relationships.md)).

Sections can also be conditionally visible via Ripple — show a "Soil Contamination" section only if "Contamination Detected" = Yes.

> **Caution:** Section IDs are regenerated each time you save the archetype. Don't bake section IDs into Ripple formulas — use label-based operators (`rowCount`, `repeaterFieldAtRow`) instead.

***

## Status workflows

Each archetype can have a status list — the lifecycle states a Record can move through. A typical list:

* **In Progress** (initial)
* **Ready for Review**
* **Approved**
* **Rejected**

Status changes flow into the activity timeline ("Hydra") and are filterable from both web and mobile. The first status in the list (with `order: 0`) is the default for new Records.

Every Composition should have:

* A **Project Status list** — applied to the Project itself.
* A **Record Status list** — applied to each archetype's Records (can be shared across archetypes or per-archetype).

> Status list names must be ≤18 characters; an "Initial" status must be at `order: 0`.

***

## Media policy

Each archetype can have its own media gallery — separate from the Project-level media gallery on Project Details.

When configuring:

* **`canHaveMedias: true`** enables the gallery.
* **At least one media subtype** must be defined (Photo, Video, File, etc.). An archetype with media enabled but no subtypes configured won't save.
* **Each subtype can have its own metadata fields** — these are the "Step 2" upload fields crews fill in after taking a photo.

See [Mobile: Capturing Photos & Media](/codifi-docs/mobile-app/capturing-photos-and-media.md) for the field-side view.

***

## Common pitfalls

* **Treating photo collections as their own archetype.** Don't make a "Photo" archetype. Photos belong as **media** on whatever Record they document (Site, Feature, etc.) using media subtypes.
* **Splitting variants by parent.** Multi-parent archetypes are supported. "Field STP" + "Transect STP" as two archetypes adds complexity for no benefit.
* **Adding prefixes to labels.** Archetype `label` is what crews see; don't prefix with state codes or Composition codes. The `name` field handles uniqueness.
* **Hardcoding section IDs.** Section IDs change on save. Reference by label or use repeater-aware Ripple operators.
* **Forgetting a title field.** An archetype with no title field won't save. Pick a SingleLine Text field and mark it as the title before publishing.

***

## Related

* [Fields & Field Types](/codifi-docs/web-app/composition-builder/fields-and-field-types.md) — what goes inside an archetype
* [Project Details](/codifi-docs/web-app/composition-builder/project-details.md) — the special root archetype
* [Project Templates](/codifi-docs/web-app/composition-builder/project-templates.md) — packaging archetypes into a usable Composition
* [Ripple — Value Formulas](/codifi-docs/cross-platform-features/ripple/value-formulas.md) — formulas you'll use for titles, calculated fields, and parent-name inheritance
* [Mobile: Record Auto-Numbering](/codifi-docs/mobile-app/mobile-project-settings/record-auto-numbering.md) — how title-field number suffixes auto-increment in the field