# Content Management Structure

## Overview

This document describes the data-driven content architecture for Hershel's Bunker. All narrative content (chapters, insights, media) is separated from display code, making it easy to edit text, add media, or restructure content without touching component code.

## Directory Structure

```
include/content/
├── chapters.json          # Main chapter configuration (NEW)
├── insight/
│   ├── insights.json      # Insight/media content (EXISTING)
│   └── [insight-id]/      # Asset folders per insight
│       └── *.jpg          # Image files
└── video/
    └── *.mp4              # All video files
```

## Data Files

### 1. chapters.json

**Purpose**: Central configuration for all chapter content, metadata, and asset references.

**Location**: `/include/content/chapters.json`

**Structure**:

```json
[
  {
    "id": "chapter-1", // Unique identifier
    "number": 1, // Chapter number (1-6)
    "title": "Life Before The War", // Full chapter title
    "shortTitle": "Before War", // Optional: for compact UI
    "description": "Text...", // Intro screen description
    "videos": {
      "primary": {
        // Required: main video
        "src": "./include/content/video/file.mp4",
        "speaker": "Rose Kohn", // Name for label
        "translateX": -100 // CSS transform for positioning
      },
      "secondary": {
        // Optional: second video
        "src": "./include/content/video/file2.mp4",
        "speaker": "Murray Ressler",
        "translateX": -100
      }
    },
    "insights": [
      // Array of insight IDs
      "witness-ksiazek", // References insights.json
      "another-insight-id"
    ],
    "sceneConfig": {
      // 3D scene configuration
      "id": "chapter-1-scene" // Scene identifier for Needle Engine
    }
  }
]
```

**Fields**:

- `id` (string, required): Unique identifier, use kebab-case
- `number` (number, required): 1-6, determines order
- `title` (string, required): Full chapter title for displays
- `shortTitle` (string, optional): Abbreviated title for compact UI
- `description` (string, required): Intro text shown on title screen
- `videos` (object, required):
  - `primary` (object, required): Main video configuration
    - `src` (string): Path to video file
    - `speaker` (string): Name shown as label
    - `translateX` (number): CSS transform for positioning
  - `secondary` (object, optional): Second video, same structure as primary
- `insights` (array of strings): IDs matching entries in `insights.json`
- `sceneConfig` (object): Configuration for 3D scene loading

---

### 2. insights.json

**Purpose**: Additional content like eyewitness accounts, historical documents, photos.

**Location**: `/include/content/insight/insights.json`

**Structure**:

```json
[
  {
    "id": "witness-ksiazek", // Unique identifier
    "title": "Wladislaw Ksiazek", // Display title
    "subtitle": "Eye Witness, July 1942",
    "gallery": [
      // Array of images
      {
        "url": "./include/content/insight/witness-ksiazek/img1.jpg",
        "alt": "Gallery Image 1"
      }
    ],
    "quote": [
      // Array of quote paragraphs
      "First paragraph...",
      "Second paragraph..."
    ],
    "links": [
      // External resources
      {
        "label": "Link 1",
        "url": "https://example.com"
      }
    ]
  }
]
```

**Fields**:

- `id` (string, required): Unique identifier referenced in `chapters.json`
- `title` (string, required): Main heading
- `subtitle` (string, optional): Subheading or context
- `gallery` (array, required): Image assets
  - `url`: Image path (jpg, png, etc.)
  - `alt`: Accessibility description
- `quote` (array of strings): Testimonial or description paragraphs
- `links` (array): Related resources

---

## Content Organization Guidelines

### Naming Conventions

**Chapter IDs**: Use `chapter-[number]` format

- Example: `chapter-1`, `chapter-2`

**Insight IDs**: Use descriptive kebab-case

- Example: `witness-ksiazek`, `document-ghetto-order`, `photo-family-home`

**Video Files**: Use descriptive names with chapter prefix

- Pattern: `[chapter]-[subject]-[detail]_[resolution].mp4`
- Example: `01-Hb-Rose-houseintro_480.mp4`

**Image Folders**: Match insight ID

- Example: `/insight/witness-ksiazek/`

### Asset Management

**Videos**:

- Store all in `/include/content/video/`
- Use consistent resolution suffix (e.g., `_480.mp4`)
- Reference full path in `chapters.json`

**Images**:

- Create subfolder per insight: `/insight/[insight-id]/`
- Add image files (JPG, PNG)

### Linking Content

**Chapters to Insights**:

```json
{
  "id": "chapter-3",
  "insights": ["witness-ksiazek", "document-liquidation"]
}
```

**Insight Must Exist**: Each ID in `insights` array must match an `id` in `insights.json`

---

## Editing Content

### Adding a New Chapter

1. Open `/include/content/chapters.json`
2. Add new object to array:

```json
{
  "id": "chapter-7",
  "number": 7,
  "title": "New Chapter",
  "shortTitle": "New",
  "description": "Chapter description...",
  "videos": {
    "primary": {
      "src": "./include/content/video/07-video.mp4",
      "speaker": "Speaker Name",
      "translateX": -100
    }
  },
  "insights": [],
  "sceneConfig": {
    "id": "chapter-7-scene"
  }
}
```

3. Upload video to `/include/content/video/`
4. Update `TOTAL_CHAPTERS` in `Timeline.svelte` if needed

### Adding a New Insight

1. Create folder: `/include/content/insight/[new-id]/`
2. Add images (fg, bg, full versions)
3. Open `/include/content/insight/insights.json`
4. Add new entry:

```json
{
  "id": "new-id",
  "title": "Title",
  "subtitle": "Context",
  "gallery": [
    {
      "url": "./include/content/insight/new-id/img1.jpg",
      "alt": "Description"
    }
  ],
  "quote": ["Quote text..."],
  "links": []
}
```

5. Reference in chapter: Add `"new-id"` to chapter's `insights` array

### Updating Text

**Chapter Descriptions**:

- Edit `description` field in `/include/content/chapters.json`
- Supports long paragraphs
- HTML not supported, plain text only

**Insight Quotes**:

- Edit `quote` array in `/include/content/insight/insights.json`
- Each array element = new paragraph

---

## Component Integration

### Components That Consume This Data

**ChapterView.svelte**:

- Loads `chapters.json` on mount
- Looks up chapter by number
- Passes data to child components

**Insights.svelte**:

- Already loads `insights.json`
- Filters by ID from chapter reference

**TitleScreen.svelte**:

- Receives: `title`, `description` from chapter data

**VideoPlayer.svelte**:

- Receives: video sources, speaker names, positioning from chapter data

### Implementation Example

```svelte
<script>
  import { onMount } from 'svelte';

  let chapters = [];
  $: chapterData = chapters.find(ch => ch.number === chapterNumber);

  onMount(async () => {
    const res = await fetch('/include/content/chapters.json');
    chapters = await res.json();
  });
</script>

<TitleScreen
  title={chapterData?.title}
  description={chapterData?.description}
/>
```

---

## Benefits of This Structure

✅ **Separation of Concerns**: Content editors don't touch code
✅ **Easy Maintenance**: Update text/media in JSON files only
✅ **Consistency**: Enforced structure across all chapters
✅ **Extensibility**: Add fields without breaking existing code
✅ **Version Control**: Track content changes separately from code
✅ **Validation**: JSON format ensures structural integrity
✅ **Localization Ready**: Easy to create alternate language versions
✅ **Asset Organization**: Clear folder structure, easy to find files

## Future Enhancements

**Possible additions to schema**:

- `metadata`: Date ranges, historical context
- `audioNarration`: Background audio file paths
- `interactiveElements`: Hotspots, clickable objects in 3D scene
- `relatedChapters`: Cross-references between chapters
- `timeline`: Specific date/time information
- `locations`: Geographic data for mapping
- `characters`: People featured in chapter
- `translations`: Multi-language support

**Example extended schema**:

```json
{
  "id": "chapter-1",
  "metadata": {
    "dateRange": "1920-1939",
    "location": "Rozanka, Poland",
    "historicalContext": "Pre-war period"
  },
  "characters": [
    {"name": "Rose Kohn", "role": "Survivor"},
    {"name": "Murray Ressler", "role": "Survivor"}
  ],
  "translations": {
    "en": { "title": "Life Before The War", ... },
    "pl": { "title": "Życie przed wojną", ... }
  }
}
```