Skip to documentation content

Projects

The central record in Vellum: every piece of work, file, and event ties back to one.

What is a project?#

A project represents a single piece of work for a client — a renovation, a licensing process, a new build. Every project belongs to exactly one company and one location (branch), is associated with one client, and has one responsible employee.

Within a company, the project's identifier must be unique. Two projects can share an address or client, but never the same identifier.

Fields#

These are the fields you'll see when you create or edit a project:

identifier
stringrequired
A short code unique within your company (e.g. `2025-014`). Used as the human-readable name across the app.
client
relationrequired
The client this project is for. Required.
location
relationrequired
Which of your office branches owns this project. Required.
project_type
relationoptional
Optional template that pre-seeds stages.
responsible_employee
relationoptional
An employee who answers for the project. Optional but recommended.
address
stringoptional
The site address (the project's, not the client's).
dates
DateTimeoptional
`start_date`, `end_date`, `ready_date`, `concluded_date` — set as the project moves through states.
description
textoptional
Free-text notes about the project.

States#

Every project sits in one of five states. The state is yours to set — Vellum doesn't auto-transition between them based on file approvals or stage progress.

Lifecycle#

A typical project moves through these states roughly in order, but jumping back is supported (e.g. moving Concluded → Ongoing if a client comes back with changes):

  • New — created but not yet started.
  • Missing Documentation — work paused waiting on client paperwork.
  • Ready — all inputs in hand, ready to begin.
  • Ongoing — actively being worked on.
  • Concluded — delivered.

Deletion behaviour#

Deleting a project is a soft-delete: the row stays in the database with a `deleted_at` timestamp and disappears from listings. There is no in-product restore, but the data isn't lost — contact support if you need a record back.

Stages and stage files cascade with the project. Events that were linked via `ProjectEvent` are not deleted; they remain on the calendar but with no project association.