> 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-templates.md).

# Project Templates

A **Project Template** is the packaged version of a Composition — archetypes, fields, Project Details, status lists, and the relationship tree, all wired together and ready to spawn new Projects.

When a user creates a new Project from a template, Codifi takes a **complete snapshot** of the template at that moment. The new Project keeps that snapshot for its entire life, even as the underlying Library entities continue to evolve.

This page is about how that snapshot model works, why it matters, and how to think about template lifecycle.

***

## What a Project Template contains

| Element                           | What it does                                                               |
| --------------------------------- | -------------------------------------------------------------------------- |
| **Project Details schema**        | The one-per-Project archetype that holds Project metadata                  |
| **Relationship tree**             | The list of archetypes and how they can be parents/children of each other  |
| **Default Project Status list**   | What lifecycle states a new Project can be in                              |
| **Default Record Status list(s)** | The lifecycle states for Records (can be one shared list or per-archetype) |
| **Default Project Members**       | Optional — pre-populate certain members on every new Project               |
| **Default overlays / map style**  | Optional — pre-set the Project map configuration                           |
| **Template metadata**             | Name, description, version, status (Draft / Published)                     |

***

## Draft vs Published

Templates have a status of either **Draft** or **Published**.

* **Draft** templates are visible only to Composers and admins. Useful while you're still iterating on the Composition.
* **Published** templates appear in the Project creation modal, so any user with Project-creation rights can start a Project from them.

> **Heads up:** Draft templates don't appear in the Project creation modal by default. If you just authored a template and can't see it there, either publish it first, or use the Draft toggle to surface Draft templates in the picker.

***

## The snapshot rule

This is the rule that **every** new Composer trips over at least once, so know it cold:

> **When a Project is created from a template, Codifi snapshots the entire template state into the Project at that moment. Subsequent changes to Library entities or to the template itself do NOT propagate to existing Projects.**

What this means in practice:

| Scenario                                                     | Result                                                                                  |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| You fix a typo on a Library field's label.                   | New Projects show the fix. Existing Projects do not.                                    |
| You add a new field to an archetype.                         | New Projects have the field. Existing Projects do not.                                  |
| You add a new archetype to the template's relationship tree. | New Projects have it. Existing Projects do not.                                         |
| You change the Ripple formula on a calculated field.         | New Projects use the new formula. Existing Projects use the formula they snapshotted.   |
| You delete an archetype from the Library.                    | New Projects don't have it. Existing Projects continue to function with their snapshot. |

This decoupling is by design. It means existing field Projects never break under your feet because someone edited the Library — but it also means **fixes don't reach existing Projects**, and **fixing an existing Project requires per-Project editing** (or migrating the Project to a new template version).

***

## Working with the snapshot rule

Practical ways to manage the snapshot:

**For active fixes to a live Project:**

* Make the change directly on that Project (overriding its snapshot). This is what the Web Project workspace's archetype-edit screens are for.
* Then make the same change in the Library so future Projects benefit.

**For releasing template improvements:**

* Bump the template version (`v1` → `v2`) so the change is intentional and tracked.
* Communicate to Project leads that new Projects from now on will use v2.
* If existing Projects need v2, migrate them deliberately (manual per-archetype patching, or a fresh Project with data import).

**For development workflow:**

* Author and iterate freely in the Sandbox tenant — changes there are expected.
* Once stable, promote to the Projects tenant.
* After promotion, treat the Projects tenant's templates as more conservative.

***

## Template embed: archetypes are snapshotted *into* the template

A subtler nuance:

The template doesn't just *reference* its archetypes — when you save the template, it **embeds** a snapshot of each archetype directly. So the template itself carries a copy of every archetype's fields, formulas, and styles at template-save time.

Saving the template re-snapshots from the Library, so:

* **Edit an archetype in the Library → re-save the template** to pull the change into the template's embed.
* **Edit an archetype in the Library but don't re-save the template** → new Projects from the template still use the *old* archetype snapshot embedded in the template.

This is the second-most-common Composer gotcha after the Project-snapshot rule. **Always re-save the template after editing its archetypes** if you want new Projects to pick up the change.

The flip side: the web app caches what each template "looks like" until the template itself is saved. After making bulk archetype changes, re-save the template — even with no other edits — to make sure crews see the new version on their next sync.

***

## Cross-tenant promotion

Most orgs run a Sandbox tenant for authoring and a Projects tenant for live work. To promote a template:

1. **In Sandbox**, finalize the template and confirm it works with a test Project.
2. **In Projects**, recreate every Library entity the template depends on: archetypes, fields, value lists, status lists, Ripple formulas.
3. **In Projects**, build the template referencing the new entities.
4. **Set Status: Published** in Projects.
5. Crews can now create real Projects from the Projects-tenant template.

Some orgs script this promotion to avoid manual recreation. If you're not sure whether yours does, ask your Composition lead — manual recreation is the safe default but error-prone.

***

## Template lifecycle

A typical template's life:

```
Draft (Sandbox)
   │  iterate + test
   ↓
Published (Sandbox)         ← used for training and validation
   │  promote
   ↓
Draft (Projects)
   │  final QA
   ↓
Published (Projects)        ← live client work
   │  ongoing maintenance
   ↓
Versioned (v2, v3, …)      ← deliberate template improvements
   │  eventual retirement
   ↓
Archived                   ← no new projects, existing keep running
```

Templates are rarely deleted — even retired templates need to stay around because existing Projects (with their snapshots) keep working even after the template is no longer used for new Project creation.

***

## Common pitfalls

* **Editing archetype + forgetting to re-save the template.** The archetype change exists in the Library but isn't in the template embed, so new Projects don't get it.
* **Expecting Library edits to propagate to existing Projects.** They don't. Project-level edits are required for active Projects.
* **Looking for a Draft template in the Project creation modal.** Draft templates don't appear by default — publish first, or enable the Draft toggle to surface them.
* **Renaming a template versus versioning it.** Renaming changes the display name but doesn't help users distinguish iterations. Use versioned suffixes (`v2`, `v3`) when behavior changes.
* **Promoting Sandbox to Projects by export-import.** Cross-tenant cloning can fail silently on referenced entities (fields, formulas). Verify every entity resolves in the destination before publishing.

***

## Related

* [Archetypes & Relationships](/codifi-docs/web-app/composition-builder/archetypes-and-relationships.md) — what gets embedded into a template
* [The Library](/codifi-docs/web-app/composition-builder/library.md) — where the archetypes that templates reference live
* [Project Details](/codifi-docs/web-app/composition-builder/project-details.md) — the special archetype templates require
* [Ripple — Real-World Examples](/codifi-docs/cross-platform-features/ripple/examples.md) — formula patterns that depend on template structure
* [Creating a Project](/codifi-docs/getting-started/creating-a-project.md) — what users see when they spin up a Project from a template