projects

This table stores project records within a tenant. Each row represents one construction project and acts as the root record for project-scoped modules such as Drawings, Forms, RFIs, Documents, Photos, Scheduling, and related collaboration data.

Domain: Projects

Scope: Tenant / Project

Status: Proposed

Last Updated: 11 Apr 2026

Mutable: Yes

Primary Owner: Projects / Core API

RLS Applies: Yes

Client Facing: Yes

Purpose

The purpose of this table is to define the core project entity inside a tenant. It provides the shared project context that links users, documents, drawings, forms, workflows, and notifications.

What this table does

Stores core project metadata such as name, address, and lifecycle status
Acts as the parent record for most project-scoped modules
Defines which modules are enabled for the project
Provides the main unit for project membership, project settings, and collaboration

Why this table is defined

DirtView is project-centric. Most daily activity happens in the context of a project, not just a tenant. This table is defined so the platform can cleanly group operational work, files, permissions, and workflows at the project level.

Columns

Column	Type	Required	Description	Example
`id`	uuid	Yes	Primary key for the project record	`project_phoenix`
`tenant_id`	uuid	Yes	Tenant that owns the project	`tenant_001`
`name`	text	Yes	Project name shown in the app	`Phoenix Tower Renovation`
`address`	text	No	Project address or location summary	`125 West Market St, Dallas, TX`
`status`	text	Yes	Current project status	`active`
`enabled_modules`	text[]	Yes	List of enabled modules for the project	`{drawings,forms,rfis,documents}`
`owner_name`	text	No	Owner or owner-side organization name	`Market Street Holdings`
`gc_name`	text	No	General contractor name	`BuildRight GC`
`start_date`	date	No	Planned or actual start date	`2026-04-01`
`end_date`	date	No	Planned or actual completion date	`2026-12-15`
`metadata`	jsonb	Yes	Flexible project metadata for future growth	`{"cost_code_system":"CSI"}`
`created_at`	timestamptz	Yes	Creation timestamp	`2026-04-01 10:00:00+00`
`updated_at`	timestamptz	Yes	Last update timestamp	`2026-04-11 10:45:00+00`
`deleted_at`	timestamptz	No	Soft-delete timestamp if archived or retired	`NULL`

Relationships

tenant_id → tenants.id
id is referenced by project_members.project_id
id is referenced by project_contacts.project_id
id is referenced by distribution_groups.project_id
id is referenced by files, drawings, forms, RFIs, and other project-scoped tables

How it is used

Loaded in project list and dashboard views
Used to scope access and collaboration within a tenant
Used by modules like Drawings and Forms to organize work
Used by project membership, project settings, and notification flows
Used to determine which modules should be shown in the UI

Access and security

Project access must be controlled through project_members and RBAC
Changes to module enablement should be audited
Soft deletion is preferred over hard deletion
Project visibility must respect tenant isolation and project membership rules

Example scenarios

Scenario 1: New project setup

A tenant admin creates a new project and enables Drawings, Forms, and RFIs.

Scenario 2: Module-limited project

A smaller project uses only Documents and Photos, so other modules are left disabled.

Scenario 3: Archived project

The project moves from active to archived but remains visible for audit and historical access.

Notes and assumptions

This is the main project anchor table for the platform
enabled_modules is useful for fast reads even if deeper settings exist elsewhere
Use metadata for evolving fields that are not yet fully normalized