---
title: Flat vs. Composite Content Storage: The Two Paradigms
date: unknown
---

# Flat Vs. Composite Content Storage: the Two Paradigms

# Flat vs. Composite Content Storage: The Two Paradigms

One of Rezilienz's core design principles is **filesystem freedom**. Because Rezilienz treats the filesystem as the database, it does not lock you into a single, rigid directory structure. 

Instead, the Rezilienz parser natively recognizes and digests **two distinct content organization paradigms** inside your content directory. You can mix and match both paradigms side-by-side in the same project without changing a single line of configuration.

---

## The Two Paradigms at a Glance

| Feature | Flat (Simple) Mode | Composite (Folder) Mode |
| :--- | :--- | :--- |
| **Structure** | A single `.md` file in a category folder | A directory containing `index.md` + optional partials |
| **File Path** | `content/{category}/{slug}.md` | `content/{category}/{slug}/index.md` |
| **Partials** | No partial files allowed | Supports modular, private `_*.md` internal files |
| **Best For** | Documentation, standard blog posts, single articles | Long-form narratives, dossiers, modular segmented essays |
| **Metadata** | Fully self-contained in YAML frontmatter | Defined in `index.md`; inherited by partial files |

---

## 1. Flat (Simple) Storage Mode

Flat storage is the classic markdown-folder paradigm used by traditional static site generators. 

### How it looks on your disk:
```text
content/
└── public/
    ├── comparison.md
    ├── theme-adding.md
    └── what-is-rezilienz.md
```

### Key Characteristics:
*   **Zero Ceremony**: Each article is a single, isolated file. 
*   **High Performance**: Extremely easy to search, rename, and edit inside any standard Markdown editor (like Obsidian, VS Code, or Typora).
*   **Automatic Category Binding**: If an article does not explicitly declare a `category` or `type` in its YAML frontmatter, the Rezilienz engine dynamically infers the category from its parent directory name (in this case, `public`).

---

## 2. Composite (Folder) Storage Mode

Composite storage is a unique Rezilienz innovation designed for complex, modular, or heavily structured content (like investigative journalism, character dossiers, or highly segmented narratives).

### How it looks on your disk:
```text
content/
└── person/
    └── jeffbezos/
        ├── index.md           # The canonical entry point and metadata carrier
        ├── _summary.md        # Private, unindexed sub-chapter fragment
        └── _defection_log.md  # Another private narrative fragment
```

### Key Characteristics:
*   **The "Molecule" Page**: The database treats the parent directory (`harryschultz`) as a single entity node. 
*   **Private Partials (`_*`)**: Files starting with an underscore (e.g. `_summary.md`) are treated as **Internal Fragments**. 
    *   They are **excluded** from the main public graph as separate posts to prevent namespace clutter.
    *   They inherit the full chronological and logical metadata of the parent `index.md`.
    *   They are dynamically stitched together by the rendering engine at runtime to present the reader with a seamless, modular article.

---

## 3. How the Rezilienz Engine Resolves Paths (Zero-Config)

When a template or API requests an article with ID `comparison` in the `public` category, the Rezilienz path resolver performs a **Smart Dual-Search Fallback**:

```mermaid
graph TD
    A[Request: public/comparison] --> B{Does composite folder exist?<br/>'public/comparison/index.md'}
    B -- Yes --> C[Load as Composite Entity]
    B -- No --> D{Does flat file exist?<br/>'public/comparison.md'}
    D -- Yes --> E[Load as Simple Entity]
    D -- No --> F[Return 404 / Not Found]
```

### Behind the Scenes:
1.  **Composite Check First**: The engine first looks for `category/slug/index.md`. If found, it parses it as a composite folder and crawls for any local `_*.md` partials.
2.  **Simple Fallback**: If the composite folder is missing, the resolver instantly searches for `category/slug.md` and loads it as a standalone, flat document.
3.  **Runtime Metadata Enrichment**: As the document is loaded, the backend dynamically checks for missing fields. If the author did not specify a category in the frontmatter, the engine extracts the parent directory name and attaches it automatically, keeping the indexer completely synchronized.

---

## Which Paradigm Should You Use?

*   Use **Flat Mode** when you are writing standard articles, document archives, quick updates, or static resource pages where all content fits comfortably inside one file.
*   Use **Composite Mode** when you have a piece of content that is too large or too varied for a single file—such as a profile that has a public biography, a private timeline, and confidential metadata fragments that you want to manage separately in your workspace.