> 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/project-details.md).

# Project Details

**Project Details** (often abbreviated **PD**) is a special archetype that sits at the top of every Composition. It holds **Project-level metadata** — the Project name, date range, principal investigator, client, jurisdiction, anything that's true for the Project as a whole rather than for individual Records.

Unlike a regular archetype, Project Details has exactly **one instance per Project**. There's no creating multiple Project Details Records. The PD Record is created automatically when the Project is created.

***

## What Project Details is for

PD typically holds:

* **Project name** — the human-facing name of the Project.
* **Project date range** — start and end dates.
* **Client / Customer** — who the Project is being done for.
* **Principal Investigator (PI)** or **Project Manager**.
* **Jurisdiction / Agency** — which SHPO, regulator, or oversight body applies.
* **Location summary** — county, state, township-range, watershed.
* **Project number / job number** — internal tracking ID.
* **Status** — Active, On Hold, Complete (from the Project status list).
* **Any Project-level overlays / references** that aren't structural.

Records of *any* archetype in the Project can read from PD via Ripple — e.g., a child Site Record can inherit the Project's date range, name, or jurisdiction.

***

## The DateRange requirement

Project Details **must include a DateRange-typed field**. Codifi won't accept a Project Details setup that uses only SingleDate or no date field at all.

If your Project doesn't have meaningful start/end dates, configure the DateRange anyway — leave the values empty or use placeholder dates that your reports treat as "unknown."

> This is the most common reason a new Composition won't save. Verify the PD has a DateRange field before publishing.

***

## PD is not a regular archetype

A few important differences from regular archetypes:

| Aspect                    | Regular Archetype              | Project Details                            |
| ------------------------- | ------------------------------ | ------------------------------------------ |
| **Instances per Project** | Many                           | Exactly one                                |
| **Creation**              | Crew creates from the + button | Auto-created when Project is created       |
| **Has parent in tree**    | Yes (or root)                  | Root by definition                         |
| **Has children**          | Yes                            | Yes (everything else in the Project)       |
| **Geometry**              | Optional                       | Usually none — or polygon for Project area |
| **Required DateRange**    | Optional                       | **Required**                               |
| **Title field**           | SingleLine                     | SingleLine (same rule)                     |

The title field on PD is, by convention, **the Project name**. Crews rename a Project by editing this field — there's no separate "Rename Project" button.

***

## Map geometry on Project Details

You can configure PD with a polygon location — common for showing the **Project area**, **APE** (area of potential effect), or **survey boundary** on the map.

When you do this:

* The PD polygon shows on the mobile map alongside Record archetypes.
* Crews can edit the polygon from the PD Record's location card.
* Reports can read the polygon's area, perimeter, and bounds via Ripple spatial operations.

For more complex setups (multiple boundary types — e.g., "Project Area"

* "APE" + "Buffer Zone"), make those separate archetypes that are **children of PD** rather than fields on PD.

***

## Ripple on Project Details

PD is a Ripple-rich archetype in most Compositions. Common patterns:

* **PD as a configuration broker.** A boolean field on PD ("Apply QA checks") that cascades to every child Record's behavior — a Ripple formula on the child reads up the family tree to find the PD value. See [Cascading PD toggle](/codifi-docs/cross-platform-features/ripple/examples.md).
* **PD as a name source.** Child archetypes' Ripple titles read `{parent.title}` (recursively walking up to PD) to inherit the Project name.
* **PD as a counter.** Aggregation formulas on PD (count of features, sum of artifact weights) provide Project-wide rollups.

> **Heads up:** Ripple geometry operations like `hasLocation` and `locations` only work reliably on regular archetypes. On Project Details they often return empty results — keep spatial formulas on the child archetypes that actually have geometry.

***

## Required Project status list

In addition to PD itself, every Composition needs a **Project Status list** referenced by PD. The list defines the lifecycle states a Project can be in.

A typical list:

* **Active** (initial — `order: 0`)
* **In QA Review**
* **Complete**
* **On Hold**
* **Archived**

Rules from the Library:

* Status names ≤ 18 characters.
* One status must be marked **Initial** at `order: 0`.
* The initial status is what new Projects get when created.

***

## Common pitfalls

* **No DateRange field.** PD won't save without one. If you're stuck on a save error, this is almost always the cause.
* **Trying to make PD have multiple instances.** PD is singleton per Project — there's no "Add another PD" path. If you need multiple Project-level Records, make them regular archetypes that are children of PD.
* **Setting PD title to MultiLine.** Title must be SingleLine, same as any archetype.
* **Naming the Project via the Project list.** There's no rename button; edit the PD title field to rename a Project.
* **Forgetting the Project Status list.** No status list = the Project can't have a status, which breaks the workspace status filter.

***

## Related

* [Archetypes & Relationships](/codifi-docs/web-app/composition-builder/archetypes-and-relationships.md) — the parent doc for archetype rules
* [Fields & Field Types](/codifi-docs/web-app/composition-builder/fields-and-field-types.md) — what kind of fields PD supports
* [Project Templates](/codifi-docs/web-app/composition-builder/project-templates.md) — how PD becomes part of the template snapshot
* [Ripple — Real-World Examples](/codifi-docs/cross-platform-features/ripple/examples.md) — common PD formulas