file_links

This table associates a file record with a business resource such as a project, certification, drawing set, form submission, or workflow item.

Domain: Files & Storage

Scope: Tenant

Status: Proposed

Last Updated: 11 Apr 2026

Mutable: Yes

Primary Owner: Storage / Core API

RLS Applies: Yes

Client Facing: Indirectly

Purpose

The purpose of this table is to create a flexible, reusable association layer between files and the records that use them without forcing every module to implement file references differently.

What this table does

Connects files to business resources
Supports one file being linked to different resource types
Provides a uniform file-association pattern across the platform
Allows files to be discovered from the owning resource and vice versa

Why this table is defined

DirtView has many modules that use files. Instead of scattering file foreign keys differently across every table, a generic linking model improves consistency and makes file management more flexible.

Columns

Column	Type	Required	Description	Example
`id`	uuid	Yes	Primary key for the link record	`flink_001`
`tenant_id`	uuid	Yes	Tenant that owns the file association	`tenant_001`
`file_id`	uuid	Yes	File being linked	`file_001`
`resource_type`	text	Yes	Type of resource the file is attached to	`drawing_set`
`resource_id`	uuid	Yes	ID of the target resource	`dset_001`
`label`	text	No	Optional contextual label for the link	`source_pdf`
`created_at`	timestamptz	Yes	Creation timestamp	`2026-04-11 10:05:00+00`

Relationships

tenant_id → tenants.id
file_id → files.id
resource_id points to a record identified by resource_type

How it is used

Used when attaching uploads to business records
Used to fetch files related to a project, drawing set, or certification
Allows generic file UI components to work across modules

Access and security

Access to the linked file must still respect the target resource’s rules
Do not rely on this table alone for authorization
Validate resource ownership carefully when creating links

Example scenarios

Scenario 1: Drawing set source PDF

A drawing source PDF is linked to a drawing set via resource_type=drawing_set.

Scenario 2: Certification document

A file is linked to a certification record for download and review.

Scenario 3: Project document

A file is linked directly to a project’s document area.

Notes and assumptions

This is a polymorphic association table
Consider indexing (resource_type, resource_id) for fast lookups
Use consistent naming for resource_type values