# Content modeling (/docs/guides/content-modeling)

AISquare organizes content into a hierarchy. Understanding it is the key to
building feeds, learning flows, and discovery pages that render cleanly.

```text
AI Studio (Publication)
 |-- Experiences
 |     '-- Resources
```

For the entities themselves, see [Core
Concepts](/docs/getting-started/core-concepts). This guide focuses on turning
them into UI.

## Building blocks [#building-blocks]

### AI Studio [#ai-studio]

The top-level container: a workspace, a content hub, a themed collection of
experiences. It is addressed by a `url`, for example `ai-research-studio`.

### Experience [#experience]

A logical grouping of content, such as a topic, a module, or a journey. Example:
"Advanced Machine Learning Models." An experience is a container, not a content
item.

### Resource [#resource]

The actual content unit. An experience holds many resources, and each resource
has a type.

| Type        | Use case                       |
| ----------- | ------------------------------ |
| `AI_EXPERT` | Interactive AI systems         |
| `AI_NOTE`   | Educational or written content |
| `QUEST`     | Challenges or tasks            |
| `PODCAST`   | Audio content                  |

## Two response formats [#two-response-formats]

AISquare returns content in two shapes.

### Flattened (recommended) [#flattened-recommended]

Each resource comes back as its own item, with the parent experience repeated on
each row.

```json title="Flattened item"
{
  "experience_title": "Advanced Machine Learning Models",
  "resource_type": "AI_EXPERT",
  "resource_title": "Image Classification Expert"
}
```

It looks redundant, and that is the point: a frontend can render the rows as a
flat list with no joining. Use it for feeds, search results, and discovery
pages.

### Nested [#nested]

Experiences contain their resources inside them. Use it for a detailed
experience view or a structured content page, where the grouping matters.

## UI patterns [#ui-patterns]

### Feed [#feed]

The common case. Use flattened data to build a scrollable list.

```text
[ AI Expert Card ]
[ AI Note Card ]
[ Quest Card ]
```

### Grouped by experience [#grouped-by-experience]

Group resources under their experience for a sectioned layout.

```text
Experience: Advanced ML
  - AI Expert
  - AI Note
```

### Collection [#collection]

Use [collections](/docs/studios/collections) to build playlists, courses, and
learning paths from ordered groups of experiences.

## Mapping fields to UI [#mapping-fields-to-ui]

| API field          | UI usage                 |
| ------------------ | ------------------------ |
| `experience_title` | Section header           |
| `resource_title`   | Card title               |
| `resource_type`    | Badge or icon            |
| `cover_image`      | Thumbnail                |
| `creator`          | Author info              |
| `metrics`          | Likes, views, engagement |

## Rendering by resource type [#rendering-by-resource-type]

Different types call for different layouts. Branch on `resource_type`:

```python title="Render by type"
if resource_type == "AI_EXPERT":
    show_interactive_ui()
elif resource_type == "AI_NOTE":
    show_reading_layout()
elif resource_type == "QUEST":
    show_challenge_ui()
```

## Using metrics [#using-metrics]

Each item carries engagement `metrics`. Use them to sort (trending, popular),
highlight popular content, and surface engagement in the UI. See the metrics
section of [Core Concepts](/docs/getting-started/core-concepts) for what is
tracked.

## Designing for scale [#designing-for-scale]

As content grows:

* **Paginate.** Do not load everything at once.
* **Lazy load.** Fetch more as the user scrolls.
* **Cache.** Reuse responses for frequently accessed data.

See [Search and filtering](/docs/guides/search-and-filtering) for the list
parameters that drive all three.

## Common mistakes [#common-mistakes]

* **Treating experiences as content.** An experience is the container; a
  resource is the content.
* **Ignoring resource types.** Each type needs its own UI handling.
* **Overfetching.** Always use pagination and filters.

## Putting it together [#putting-it-together]

1. Fetch flattened resources.
2. Map each item to a UI card.
3. Group or filter if needed.
4. Render as a feed or sections.

## Next steps [#next-steps]

<Cards>
  <Card title="Core Concepts" href="/docs/getting-started/core-concepts" description="The entity hierarchy behind these responses." />

  <Card title="Studios" href="/docs/studios/overview" description="Fetch experiences and resources from a studio." />

  <Card title="Collections" href="/docs/studios/collections" description="Group experiences into playlists and paths." />

  <Card title="Search and filtering" href="/docs/guides/search-and-filtering" description="Refine, sort, and page through results." />
</Cards>