# 📱 CMS & Harmonic Builder: API Integration Guide

This document outlines the public CMS endpoints, specifically detailing the User Guide endpoint which now powers the dynamic **Harmonic Builder** UI in the Flutter app.

---

## 1. Fetching the User Guide (including Harmonic Builder)
**Endpoint:** `GET /api/cms/user-guide`

This endpoint returns the tabs for the User Guide. The `harmonic_builder` tab contains a special `tiles` array which holds the structured data for rendering the Harmonic Builder screens.

**Expected Payload:**
```json
{
  "success": true,
  "message": "User guide retrieved successfully.",
  "data": [
    {
      "tab": "getting_started",
      "heading": "Welcome to NumoniX",
      "intro_text": "FNH teaches you to see the relationships...",
      "sections": [
        {
          "id": 1,
          "heading": "How to Approach Learning FNH",
          "items": [
            {
              "id": 1,
              "title": "Start with the Tier 1 foundational lessons.",
              "body": "These will show you the fixed numeric system..."
            }
          ]
        }
      ]
    },
    {
      "tab": "harmonic_builder",
      "label": "Harmonic Builder",
      "heading": "Composition Builder",
      "intro_text": "When you unlock the Composition Builder...",
      "tiles": [
        {
          "id": "1",
          "section": "Getting Started with the Builder",
          "title": "Access via Library",
          "body": "Tap beats on the sentence skeleton grid to place chords.",
          "images": [
            {
              "src": "http://leemcwest-backend.test/storage/cms/user-guide/sample1.png"
            }
          ],
          "keys": [
            "1",
            "2"
          ]
        }
      ]
    }
  ]
}
```

### Flutter Implementation Notes for Harmonic Builder:
* **`id`**: This is the database ID of the item (e.g., `"1"`). This should be used to uniquely identify or link the tile instead of relying on string anchor IDs.
* **`images`**: An array of image objects. The `src` property provides the full absolute URL to the image on the server. If a tile has no images, the array will be empty (`[]`).
* **`keys`**: An array of string keys (e.g., `["1", "2"]`) which represent numbered marker keys on the UI.
* **`tiles`**: The array flattens out the sections and items into a single linear list of renderable components for the Harmonic Builder screen. The `section` string groups them visually if needed.