Attachment

A file held on a configured filesystem disk. Attachments are referenced by most other models rather than owning them, and carry their own per-user visibility rules.

Purpose

Attachment is the single record for every uploaded file: avatars, logos, reports, invoices, configuration resources, guides and website images. It stores the disk and path rather than the file itself, so storage stays behind the Laravel filesystem abstraction. An optional allow-list of users restricts who may see a given file; an empty allow-list means the file is visible to the whole organisation.

Usage

Never write to storage directly — go through the upload service, which creates and maintains these rows.

app/Services/FileUploadService.php — upload, replace, delete and batch operations
app/Observers/AttachmentObserver.php — reacts to attachment lifecycle events
app/Filament/Resources/AttachmentResource.php — staff administration
app/Jobs/ConvertAttachmentToMarkdown.php — produces the linked DocumentText
Attachment::getOrphanedAttachments() — finds files no longer referenced anywhere

Relationships

Relation	Type	Related model
`organization`	`belongsTo`	Organization
`creator`	`belongsTo`	User
`lastEditor`	`belongsTo`	User
`visibleForUsers`	`belongsToMany`	User via `attachment_user`
`userAvatars`	`hasMany`	User
`organizationLogos`	`hasMany`	Organization
`focusIndividualAvatars`	`hasMany`	FocusIndividual
`focusIndividualProfiles`	`hasMany`	FocusIndividual
`projects`	`belongsToMany`	Project via `project_attachments`
`reports`	`hasMany`	Report
`documentText`	`hasOne`	DocumentText
`configurationResources`	`hasMany`	ConfigurationResource
`invoices`	`hasMany`	Invoice
`guidePictures`, `guideFiles`	`hasMany`	Guide
`websitePostImages`	`hasMany`	WebsitePost

The model also declares an attachable morphTo, but the attachments table has no attachable_type/attachable_id columns, so it resolves to nothing.

Data shape

Table: attachments

Column	Type	Notes
`id`	`uuid`	Primary key
`display_name`	`string`	Human-facing name
`file_name`	`string`	Original client filename
`file_size`	`integer`	Bytes
`mime_type`	`string`	Detected MIME type
`file_path`	`string`	Path on the disk
`file_disk`	`string`	Filesystem disk name
`organization_id`	`uuid`	Nullable, null means public
`creator_id`, `last_editor_id`	`uuid`	Nullable, FK `users`
`metadata`	`json`	Nullable, cast to collection; `type` drives scopes
`created_at`, `updated_at`	`timestamp`	Nullable