Files
Files in projects — saved to S3, previewed by kind, with a protected project folder at the root.
Files in Alumia are first-class records: every upload, every drag-drop, every system folder is a row in the files table with metadata, ownership, and storage details.
Storage backend
File bytes live in S3. The DB row keeps:
| Field | Purpose |
|---|---|
storageKey | The S3 object key. |
storageUrl | Internal reference; downloads use short-lived signed S3 URLs after access checks. |
mimeType, size | Set at upload. |
parentId | Folder hierarchy — a file or folder is nested under another row. |
projectId | Optional link to the owning project. |
systemKind | Marks system folders (e.g. the project folder). |
isProtected | Prevents deletion or rename. |
targetFileId | Used by derived/version rows to reference the canonical file. |
Soft deletes use deletedAt. Tags and free-form metadata go in tags and metadata.
The protected project folder
Every project gets a folder created automatically with systemKind: "projectFolder" and isProtected: true. This folder is the root of the project's file browser. Agent file tools and project browsers must root here — never at the org root. Zip inspect/extract tools enforce archive size and path caps before extraction.
Saved files vs inline attachments
| Saved file | Inline attachment | |
|---|---|---|
| Where | files row + S3 object | Embedded in a chat message |
| Lifetime | Persists across sessions | Tied to the message |
| Discoverable | Yes, in the file browser | No, only via the conversation |
| Use when | The file is part of the project | The file is one-off context for a turn |
Drag-dropping into the file browser creates a saved file. Pasting or attaching directly in a chat creates an inline attachment unless you explicitly save it.
Downloading
GET /api/v1/files/:id?download=true verifies org (and project) access, then redirects to a signed object-storage URL. Inline preview (inline=true) streams or redirects with hardened CSP headers. Private files are never served from a permanent public URL.
Large uploads can use the presigned flow: create a pending record, PUT bytes to the returned URL, then POST /files/:id/finalize.
Preview kinds
The preview layer classifies each file into one of:
imagepdfvideoaudiospreadsheet(csv, xls, xlsx, ods)document(doc, docx, odt, rtf)text(md, json, source code, yaml, etc.)download(anything else — offered as a download)
Spreadsheets render natively. Documents and Markdown files render through dedicated readers. Anything not previewable falls back to a download link.
Drag and drop
The project file drag layer accepts drops anywhere a file would be useful — into a chat to attach, into the browser to save, or onto a canvas block to bind the file to that block.