Organizing Content with Folders

In FoxNose, a Folder is more than just a directory—it's the blueprint for your data model and, automatically, for your API. Getting the folder structure right is the key to a scalable and maintainable project, as it solves several common problems up front:

API Design: A folder's alias directly becomes a segment in your API URL, making your API structure a clean reflection of your data model.
Data Scoping: Folders live inside a single Environment, so you can safely manage production data separately from staging or development.
Content Structure: Folders determine how your content is structured, either through a single, consistent schema for predictable data (Collection folders) or a flexible mix of components for dynamic layouts (Composite folders).
Data Integrity: Nesting folders can enforce parent-child relationships, preventing orphaned data and simplifying queries for related content.

The content stored within these folders can then be seamlessly delivered via the Flux API, allowing you to expose different folders through various APIs to suit your application's needs.

This guide covers the two folder types and how to use them to build a powerful and logical content architecture.

Folder Types: Solving Specific Jobs

FoxNose offers two distinct folder types, each designed to solve specific content modeling challenges:

1. Collection Folders: For Predictable Data Lists

The Job: You need to manage a list of items that all have the same, predictable structure (e.g., blog posts, products, users). You value consistency and easy querying of uniform data.
Rule of thumb: If every entry should look the same, start with a Collection folder.
How it works: A Collection folder is tied to a single schema version. Every resource you add to it will have the exact same fields, ensuring data consistency and simplifying data retrieval.

Example: An "Articles" Collection

📁 Articles (Collection, alias: articles)
├── Schema Version v1
│   ├── title (string, required)
│   ├── summary (text, vectorizable)
│   └── author (reference → People)
├── 📄 article-1
├── 📄 article-2
└── 📄 article-3

In this example:

Every article resource follows the same defined schema.
References (e.g., author) can connect to other folders, enabling powerful joins and population in Flux API searches.
You can evolve the schema over time by publishing new versions, ensuring backward compatibility.

2. Composite Folders: For Flexible Content Layouts

The Job: You need to build a flexible layout from a mix-and-match set of content blocks (e.g., landing pages, dynamic sections, complex settings bundles). You value content reusability and creative freedom for editors.
Rule of thumb: If you need a flexible canvas of components to compose content, reach for a Composite folder.
How it works: A Composite folder isn't tied to a single schema. Instead, it can contain resources built from different Components. This gives you the flexibility to compose pages from various pre-defined content blocks.

Example: A "Home Page" Composite

📁 Home Page (Composite, alias: home)
├── 📄 hero-banner (component-1)
├── 📄 testimonials (component-2)
└── 📄 footer-cta (component-3)

In this example:

Each entry in the Home Page folder is a Resource that points to a specific Component (e.g., hero-banner points to the hero component).
Editors can easily add, reorder, or update these components to shape the page layout, making it ideal for highly dynamic content.

Modeling Folder Relationships

Once you have your basic folders, you'll need to connect them. FoxNose provides two primary ways to model relationships, each solving a different problem:

Nested Folders with strict_reference: Use this for compositional ownership, when one object cannot exist without its parent (like comments belonging to a post). This approach guarantees data integrity (no orphaned data) and automatically creates clean, hierarchical API URLs.
Reference Fields: Use this for many-to-many or shared relationships, where you want to link to a shared entity from multiple places (like an author who writes many posts). This is done by adding a reference field to your schema.

For a deep dive into modeling dependent data and leveraging strict_reference for hierarchical APIs, refer to the Strict-Reference Modeling guide.

Strategic Folder Design

Making the right folder choices early on prevents future headaches. Here are key recommendations:

Prioritize Collection Folders: For structured, predictable content (like blog posts or product listings), Collection folders are your go-to. They enforce consistency and simplify queries. Reserve Composite folders for when you specifically need to build flexible, block-based content layouts (e.g., landing pages).
Nesting for Ownership, References for Relationships:
- When data must belong to a parent (e.g., employee to a company), use nested folders with strict_reference. This guarantees data integrity and clean API paths.
- For many-to-many connections or linking to shared entities (e.g., tags, authors), use Reference Fields within your schemas. This avoids duplication and maintains flexibility.
Build Data Model First, Connect to Flux Last: Focus on solidifying your folder structure, schemas, and relationships. Once your content model is robust, then connect your folders to a Flux API. This "schema-first" approach ensures your APIs are well-designed and stable.