Document: 12-system-architecture.md
Version: 1.0.0

Purpose

This document defines the high-level system architecture used across all Rundown web projects.

Its purpose is to provide a clear overview of how the different parts of an application interact. While individual subsystems are documented separately, this document serves as the architectural blueprint that connects them.

Unless project-specific requirements dictate otherwise, every Rundown project should follow this architecture.

Architecture Overview

A standard Rundown application consists of the following layers:

                     User
                       │
                       ▼
              Cloudflare DNS & CDN
                       │
                       ▼
                 Nginx Reverse Proxy
                       │
                       ▼
              Next.js Application
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
  Payload CMS     PostgreSQL     Cloudflare R2
        │
        ▼
 External Services
(Payments, Email, Analytics, APIs)

Each layer has a clearly defined responsibility and should remain as independent as possible.

Architectural Principles

Every Rundown application should follow these principles:

• Separation of concerns

• Modular architecture

• Minimal dependencies

• Reusable components

• Secure by default

• Performance first

• Simplicity over unnecessary complexity

Core Components

Frontend

Responsible for:

• User interface

• Routing

• Rendering

• Client interactions

• Forms

• SEO

Standard:

• Next.js

• React

• TypeScript

• Tailwind CSS

Content Management

Responsible for:

• Content editing

• Media references

• Authentication

• Administrative interface

Standard:

• Payload CMS

Database

Responsible for:

• Structured data

• Relationships

• User accounts

• Orders

• Content metadata

Standard:

• PostgreSQL

The database stores application data only.

Large media files should not be stored directly in the database.

Object Storage

Responsible for:

• Images

• Videos

• Documents

• Client uploads

Standard:

• Cloudflare R2

Only file references should be stored inside PostgreSQL.

Hosting

Responsible for:

• Running the application

• Reverse proxy

• SSL termination

• Container management

Standard:

• Ubuntu LTS

• Docker

• Coolify

• Nginx

CDN

Responsible for:

• Global asset delivery

• DNS

• SSL

• Edge caching

• Security

Standard:

• Cloudflare

Request Flow

A typical request follows this path:

Browser
    │
    ▼
Cloudflare
    │
    ▼
Nginx
    │
    ▼
Next.js
    │
    ├── Payload CMS
    ├── PostgreSQL
    └── Cloudflare R2

The frontend coordinates communication between supporting services while presenting a unified experience to the user.

Data Flow

Application data should flow in a predictable manner.

Client

↓

Next.js

↓

Payload CMS

↓

PostgreSQL

↓

Response

Media follows a different path.

Client

↓

Cloudflare R2

↓

URL stored in PostgreSQL

↓

Frontend renders asset

Separating structured data from media storage improves scalability and reduces database size.

External Services

Applications may integrate with external services such as:

• Payment gateways

• Email providers

• Analytics platforms

• Mapping services

• CRM systems

• Third-party APIs

External services should remain isolated behind reusable service modules.

Direct integration logic should not be scattered throughout the application.

Security Principles

Every Rundown application should:

• Use HTTPS.

• Validate all user input.

• Store secrets in environment variables.

• Restrict administrative access.

• Follow the principle of least privilege.

Security is considered a responsibility of every subsystem.

Scalability

Applications should be designed so that additional features can be introduced without significant architectural changes.

Examples include:

• Additional CMS collections

• New integrations

• Additional user roles

• Expanded ecommerce functionality

• Internationalization

Scalability should come from modular design rather than unnecessary abstraction.

Engineering Decision

Standard Architecture

Status: Accepted

Decision

Rundown adopts a modular architecture centered around a single Next.js application with integrated Payload CMS, PostgreSQL, and Cloudflare R2.

Reasoning

This architecture provides:

• Strong performance

• Excellent developer experience

• Simple deployment

• Low operational cost

• Clear separation of responsibilities

It supports the majority of websites developed by Rundown without introducing unnecessary infrastructure complexity.

Architecture Checklist

Before beginning development, verify:

• Project type has been identified.

• System architecture matches Rundown standards.

• Required integrations have been identified.

• CMS requirements are defined.

• Database requirements are understood.

• Storage strategy has been confirmed.

• Authentication requirements have been reviewed.

Summary

The system architecture defines the overall structure of every Rundown application.

By standardizing how each subsystem interacts, Rundown ensures that projects remain consistent, maintainable, scalable, and cost-effective while allowing individual components to evolve independently.

Related Documents

• 02-tech-stack.md

• 03-project-types.md

• 05-project-structure.md

Related ADRs

• ADR-001: Repository Structure

• ADR-002: Git Workflow