Document: 13-architecture-boundaries.md
Version: 1.0.0

Purpose

This document defines the responsibilities and boundaries of each major subsystem within a Rundown application.

Clear architectural boundaries ensure that every technology in the stack has a well-defined purpose. By assigning responsibilities to specific layers, Rundown applications remain modular, maintainable, scalable, and easier to reason about.

When a new feature is introduced, developers should first determine which subsystem owns that responsibility before implementing it.

Architectural Philosophy

Every subsystem should have a clearly defined responsibility.

A subsystem should not perform work that properly belongs to another subsystem.

Following this principle:

• Reduces coupling.

• Improves maintainability.

• Simplifies debugging.

• Encourages modular design.

• Prevents architecture drift.

Frontend (Next.js)

Responsibilities

The frontend is responsible for presenting the application to the user.

It owns:

• Routing

• Page rendering

• User interface

• Layout composition

• Client-side interactions

• Form presentation

• User experience

• SEO rendering

Non-Responsibilities

The frontend should not own:

• Business content

• Database schema

• Media storage

• Authentication data

• Payment processing

• Content management

• Infrastructure configuration

The frontend consumes data; it should not become the source of truth.

Payload CMS

Responsibilities

Payload CMS manages structured content and administrative functionality.

It owns:

• Collections

• Globals

• Rich content

• Media references

• Content validation

• Editorial workflows

• User roles (where applicable)

• Administrative interface

Payload acts as the content source of truth.

Non-Responsibilities

Payload should not:

• Render frontend layouts

• Control animations

• Manage application styling

• Store large media binaries

• Contain frontend business logic

• Replace application architecture

PostgreSQL

Responsibilities

PostgreSQL stores structured application data.

Examples:

• Users

• Orders

• Products

• Categories

• Blog metadata

• Relationships

• Permissions

Non-Responsibilities

PostgreSQL should not store:

• Images

• Videos

• PDFs

• Backups

• Static assets

• Application configuration files

Only metadata and references should be stored where appropriate.

Cloudflare R2

Responsibilities

Cloudflare R2 stores binary assets.

Examples:

• Images

• Videos

• Documents

• Downloads

• Client uploads

Non-Responsibilities

R2 should not store:

• Business data

• User accounts

• Product information

• CMS content

• Application configuration

Object storage exists only for files.

Cloudflare

Responsibilities

Cloudflare provides edge services.

It owns:

• DNS

• SSL

• CDN

• Edge caching

• Basic request protection

Non-Responsibilities

Cloudflare should not:

• Execute business logic

• Replace application authentication

• Store application data

• Replace the application server

Docker

Responsibilities

Docker standardizes application execution.

It owns:

• Runtime environment

• Container isolation

• Dependency consistency

Non-Responsibilities

Docker should not:

• Define application architecture

• Replace deployment documentation

• Store persistent business data

Containers should remain disposable.

External Services

Examples include:

• Payment gateways

• Email providers

• Analytics

• Maps

• CRM systems

• External APIs

Responsibilities

External services provide specialized functionality outside the core application.

The application should communicate with them through isolated service layers.

Non-Responsibilities

External services should never become the primary source of business logic unless intentionally designed to do so.

Business rules should remain within the application whenever practical.

Business Logic

Business logic defines how the application behaves.

Examples include:

• Pricing calculations

• Validation rules

• Checkout rules

• Order processing

• Workflow automation

Business logic should remain within the application layer and should not be duplicated across the frontend, CMS, or external services.

Source of Truth

Every category of data should have a single source of truth.

Duplicating ownership creates inconsistency and increases maintenance complexity.

Decision Framework

When implementing a new feature, ask the following questions:

1. What responsibility does this feature represent?

2. Which subsystem owns that responsibility?

3. Does this implementation duplicate an existing responsibility?

4. Can this be implemented without violating an architectural boundary?

If ownership is unclear, the architecture should be reviewed before implementation.

Engineering Decision

Separation of Responsibilities

Status: Accepted

Decision

Every major subsystem within a Rundown application has clearly defined responsibilities and non-responsibilities.

Reasoning

Clearly defined ownership:

• Prevents architecture drift.

• Simplifies maintenance.

• Encourages modular systems.

• Reduces unnecessary coupling.

• Improves long-term scalability.

Boundary Checklist

Before implementing a feature, verify:

• The correct subsystem owns the responsibility.

• Business logic is not duplicated.

• Data has a single source of truth.

• Responsibilities remain clearly separated.

• The implementation follows Rundown architecture standards.

Summary

A well-defined architecture depends on clear ownership.

By assigning responsibilities to specific subsystems and avoiding overlapping concerns, Rundown applications remain easier to understand, extend, and maintain throughout their lifecycle.

Related Documents

• 12-system-architecture.md

• 14-frontend-architecture.md

• 15-payload-cms-architecture.md

• 16-database-architecture.md

Related ADRs

• ADR-001: Repository Structure

• ADR-002: Git Workflow