Skip to main content
Brainbox provides file upload and management capabilities with support for images, videos, PDFs, and other document types. Files integrate seamlessly with pages, databases, and chat messages.

​
Uploading Files

Files can be uploaded to multiple locations in your workspace:

Pages

Embed files directly in page content

Database Fields

Attach files to database records

Chat Messages

Share files in channels and DMs

​
Upload Methods

The easiest way to upload files:
1

Select files

Drag files from your file explorer.
2

Drop on target

Drop onto a page, database field, or chat message.
3

Upload starts

Files upload automatically in the background.

​
File Types

Brainbox categorizes files into subtypes for specialized handling:
Image files with preview and display options.Supported formats:
  • PNG, JPG, JPEG
  • GIF, WebP
  • SVG
  • HEIC (converted to JPG)
Features:
  • Inline preview in pages
  • Thumbnail generation
  • Alignment options (left, center, right)
  • Width adjustment
  • Click to expand full-size
{
  type: "file",
  subtype: "image",
  mimeType: "image/png",
  extension: "png",
  imageAlignment: "center",
  imageWidth: 600
}

​
File Structure

Each file is stored as a node with metadata: 
{
  type: "file",
  subtype: "image" | "video" | "audio" | "pdf" | "other",
  parentId: "page_abc",           // Parent page, record, or message
  name: "Screenshot 2024-03-15",  // Display name (editable)
  originalName: "IMG_1234.png",   // Original filename
  mimeType: "image/png",          // MIME type
  extension: "png",               // File extension
  size: 2458624,                  // Size in bytes
  version: "v1",                  // Version identifier
  status: 1,                      // 0=Pending, 1=Ready, 2=Error
  index: "a0",                    // Position in parent
  
  // Image-specific fields
  imageAlignment: "center",       // left, center, right
  imageWidth: 600                 // Display width in pixels
}

​
File Storage

Files are stored in S3-compatible object storage:
1

Client-side upload

Files upload directly from your browser to S3 with presigned URLs.
2

Chunked uploads

Large files split into 20MB chunks for reliable uploads and resume capability.
3

Metadata storage

File metadata saves to your local SQLite database and syncs to PostgreSQL.
4

CDN delivery

Files serve through CDN for fast global access.

​
Upload Process

// File upload configuration
const FILE_UPLOAD_PART_SIZE = 20 * 1024 * 1024; // 20MB chunks

enum FileStatus {
  Pending = 0,   // Upload in progress
  Ready = 1,     // Upload complete, file available
  Error = 2      // Upload failed
}
Large file uploads use multipart upload for reliability. If an upload is interrupted, it can resume from the last completed chunk.

​
File Permissions

File access follows parent node permissions:
ContextCreateViewEditDelete
Page/DatabaseMember+Viewer+Member+Member+
Chat MessageViewer+Viewer+Creator/AdminCreator/Admin
Files in chat messages have special permissions: only the message creator or channel admin can edit/delete them.

​
File Management

​
Renaming Files

1

Click file name

Select the file name to enter edit mode.
2

Edit name

Type a new name (extension auto-preserved).
3

Save changes

Press Enter or click outside to save.

​
Deleting Files

Deleting a file permanently removes it from storage. This cannot be undone.
1

Select file

Click the file to open its context menu.
2

Delete option

Choose Delete from the menu.
3

Confirm deletion

Confirm the deletion prompt.

​
Moving Files

Files can be moved by changing their parent:
  • Drag files between pages
  • Copy/paste files to new locations
  • Update parent via API

​
Image Handling

Images have special display features:

​
Alignment

Left

Align image to the left with text wrapping

Center

Center image with no text wrapping

Right

Align image to the right with text wrapping

​
Width Control

Adjust image width:
  • Drag handles - Resize by dragging corners
  • Preset sizes - Small (300px), Medium (600px), Large (900px), Full width
  • Custom width - Enter exact pixel value
{
  imageWidth: 600,        // Display width in pixels
  imageAlignment: "center" // Alignment option
}

​
Responsive Images

Images automatically scale for different screen sizes:
  • Desktop: Full specified width
  • Tablet: Max 90% viewport width
  • Mobile: 100% width (full bleed)

​
Offline Access

Files work with Brainbox’s offline-first architecture:
Previously viewed files cache locally:
  • Images cache in browser storage
  • Thumbnails cache separately
  • Access cached files offline
  • Cache clears based on storage limits
Only files you’ve previously opened are available offline. New files require internet connection for first download.

​
File Size Limits

Default upload limits (configurable in self-hosted deployments):
PlanSingle FileTotal Storage
Free10 MB2 GB
Pro100 MB100 GB
Enterprise1 GBUnlimited
Self-hostedConfigurableConfigurable
Self-hosted instances can configure file size limits via environment variables in the server configuration.

​
Storage Backend

Brainbox uses S3-compatible storage: Supported providers:
  • AWS S3
  • MinIO (default for self-hosted)
  • DigitalOcean Spaces
  • Backblaze B2
  • Cloudflare R2
  • Any S3-compatible service
Configuration: 
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=brainbox-files
S3_REGION=us-east-1

​
Security

Files are protected with multiple security layers:

Access Control

Files inherit permissions from parent nodes

Presigned URLs

Time-limited signed URLs for direct S3 access

Virus Scanning

Optional ClamAV integration for malware detection

Encryption

At-rest encryption via S3 bucket policies
Never share file URLs directly. Always share through Brainbox to ensure proper access control.

​
Best Practices

Compress images to reduce storage and improve load times. Use WebP format when possible for better compression.
Rename files with clear, searchable names instead of default camera names like “IMG_1234.png”.
Keep files organized in relevant pages or database records rather than uploading everything to one location.
Regularly clean up old or unused files to save storage space and keep your workspace tidy.
Verify files show Ready status before sharing links or references to ensure they’re fully uploaded.

​
Next Steps

Pages

Embed files in rich text pages

Databases

Use file fields in databases

Chat

Share files in conversations

Collaboration

Learn about offline file uploads

Build docs developers (and LLMs) love

Get started for freeTalk to us