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:

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:

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:

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.