Files
File upload, storage, and management system. Files are stored on S3-compatible storage (Tigris) and linked to any entity via a polymorphic association table. Supports image renditions, bulk operations, and label-based organization.
Source Files
| Layer | Path |
|---|---|
| Schema | backend/src/db/schema.ts |
| Routes | backend/src/routes/files/ (includes bulk operations) |
| File Service | backend/src/services/file-service.ts |
| Bulk Service | backend/src/services/bulk-file-service.ts |
| Label Service | backend/src/services/file-label-service.ts |
| Link Service | backend/src/services/entity-file-link-service.ts |
| Storage Lib | backend/src/lib/storage.ts |
| Components | frontend/src/components/files/ (25 files) |
| Queries | frontend/src/lib/queries/fileQueries.ts |
Database Tables
| Table | Purpose |
|---|---|
files | Main entity — filename, MIME type, size, storage key, rendition metadata |
entityFileLinks | Polymorphic join — links a file to any entity type (building, project, document request, etc.) |
fileUploadsMetadata | Upload tracking (progress, chunked upload state) |
fileLabelAssociations | Tags/labels applied to files for organization and filtering |
Storage Architecture
| Concern | Implementation |
|---|---|
| Object storage | S3-compatible via Tigris (TIGRIS_* env vars) |
| Upload | Presigned URLs for direct browser-to-S3 upload |
| Renditions | sharp library generates thumbnails and preview sizes |
| Background processing | Rendition generation via Background Jobs |
| Validation | MIME type checking and file size limits enforced server-side |
Entity File Links
The entityFileLinks table provides a polymorphic association pattern:
| Field | Purpose |
|---|---|
fileId | FK to files |
entityType | Discriminator string (e.g., building, project, documentRequest) |
entityId | UUID of the linked entity |
This means any entity in the system can have files attached without schema changes. Queries filter by entityType + entityId.
Frontend Components
| Component | Purpose |
|---|---|
FileUpload | Drag-and-drop upload with progress indicator |
FileAssociationManager | Link/unlink files to entities |
FileGrid / FileList | Gallery and list views for browsing files |
FilePreview | Inline preview for images and PDFs |
SyncChangelog | Displays file sync history |
FileLabelFilter | Filter files by assigned labels |
Relationships
File 1──* EntityFileLinks ──* (any entity)
File 1──* FileLabelAssociations
File *──1 Users (uploader)
Files are linked to Buildings, Projects, Documents, Document Obtaining fulfillments, Quotes, Invoices, and other entities through entityFileLinks.
Related Pages
Documents | Document Obtaining | Buildings | Projects | Background Jobs | Database Architecture | Service Layer Pattern | Deployment Pipeline