Storage Architecture

Document: 17-storage-architecture.md
Version: 1.0.0

Purpose

This document defines the storage architecture used across all Rundown projects.

Storage is responsible for managing binary assets such as images, videos, documents, and client uploads. Separating media storage from structured application data improves scalability, reduces database size, and simplifies infrastructure management.

Rundown standardizes on Cloudflare R2 as the primary object storage solution.

Storage Philosophy

Structured data and binary assets serve different purposes and should be managed separately.

The database stores information about a file.

Object storage stores the file itself.

This separation allows each system to perform the task it is designed for while keeping the overall architecture simple and scalable.

Standard Storage Platform

Rundown standardizes on:

Cloudflare R2

Reasons include:

No egress charges
S3-compatible API
Global scalability
Cost-effective storage
Easy integration with Payload CMS
Suitable for media-heavy websites

Responsibilities

The storage layer owns:

Images
Videos
Documents
PDFs
Downloads
Client uploads
Static media assets

Every uploaded file should be stored in object storage rather than on the application server.

Non-Responsibilities

Object storage should not contain:

Business records
User accounts
Orders
Products
CMS content
Application configuration
Authentication data

Only binary assets belong in object storage.

File Ownership

Each uploaded file should have:

A physical file stored in Cloudflare R2.
Metadata stored within Payload CMS and PostgreSQL.
A unique identifier.
A publicly accessible or signed URL, depending on access requirements.

This maintains a clear separation between storage and application data.

Supported File Types

Typical assets include:

Images

WebP
PNG
JPEG
SVG (trusted sources only)

Videos

MP4
WebM

Documents

PDF
DOCX
XLSX
PPTX

Additional file types may be supported based on project requirements.

Upload Workflow

Standard upload process:

User

↓

Payload CMS

↓

Cloudflare R2

↓

Metadata stored in PostgreSQL

↓

Frontend renders asset

The application should never depend on local filesystem storage for production uploads.

File Naming

Uploaded files should:

Use unique filenames.
Preserve extensions.
Avoid collisions.
Remain independent of original filenames where appropriate.

Human-readable names may be stored as metadata rather than physical filenames.

Folder Organization

Storage buckets should remain logically organized.

Example:

uploads/

images/

videos/

documents/

downloads/

Project-specific organization may introduce additional directories when justified.

Image Optimization

Images should be optimized before delivery whenever practical.

Objectives:

Reduce file size.
Preserve visual quality.
Improve loading performance.

Preferred formats:

WebP
AVIF (where supported)

Avoid serving unnecessarily large images to clients.

Access Control

Storage access should follow the principle of least privilege.

Public assets may be exposed through CDN URLs.

Sensitive assets should use signed or authenticated access where appropriate.

Examples include:

Client documents
Private downloads
Administrative reports

CDN Integration

Cloudflare should serve media assets whenever practical.

Benefits include:

Reduced latency
Global caching
Improved reliability
Reduced application server load

Media delivery should not depend on the application server after upload.

Backup Strategy

Object storage should be backed up according to project requirements.

Critical assets should support:

Versioning (when available)
Replication (when required)
Recovery procedures

Backups should be tested periodically.

Performance

Storage architecture should prioritize:

Efficient uploads
Optimized delivery
CDN caching
Minimal latency
Predictable URLs

Media optimization should occur before or during upload rather than after repeated requests.

Security

Storage should:

Restrict write access.
Validate uploaded file types.
Limit file size where appropriate.
Scan uploads when required by project specifications.
Prevent unauthorized access to protected assets.

Applications should never trust uploaded files without validation.

Engineering Decision

Object Storage Strategy

Status: Accepted

Decision

All production media assets are stored in Cloudflare R2 rather than on the application server or within the database.

Reasoning

Separating media from application data:

Improves scalability.
Reduces infrastructure costs.
Simplifies backups.
Improves performance.
Supports CDN-based delivery.

Storage Checklist

Before implementing file storage, verify:

Files are stored in Cloudflare R2.
Metadata is stored in PostgreSQL.
Upload validation is implemented.
Images are optimized.
CDN delivery is configured.
Access permissions are appropriate.
Backup requirements have been reviewed.

Summary

The storage layer is responsible for managing binary assets independently of application data.

By separating file storage from structured data, Rundown applications remain scalable, performant, and easier to maintain while providing reliable media delivery through Cloudflare's global infrastructure.

ADR-001: Repository Structure