# Comparison Table Data Structure Documentation

**Last Updated:** 2026-03-31

## Overview

The comparison table data lives in structured JSON, enabling both category-based and plan-based views with full filtering on `/preise` (`static_pricing_new.php`). **Plan cards** above the table use `v2/sections/pricing-data.php` (tooltips for long copy); the **table** uses short row labels in JSON—put detailed compatibility lists in card tooltips, not in row names.

Runtime helpers (`comparison-table-data.php`) load **`categories`** only. The top-level **`plans`** object in the JSON is a legacy/denormalized mirror; keep it loosely in sync when editing features or run a follow-up cleanup script.

## Data File

**Location:** `v2/data/comparison-table-data.json`

**Structure:**

```json
{
  "metadata": {
    "version": "1.0.0",
    "last_updated": "2026-03-31",
    "total_categories": 13,
    "total_features": 43
  },
  "categories": [...],
  "plans": {...}
}
```

## Category Structure

Each category contains:

- `id`: Unique identifier (kebab-case)
- `name`: Display name
- `slug`: URL-friendly slug
- `url`: Optional link to category page
- `order`: Display order (1-based)
- `features`: Array of features

## Feature Structure

Each feature contains:

- `name`: Feature display name
- `plans`: Object with plan availability
  - `starter`: "check" | "check_blue" | "cross" | "unknown"
  - `plus`: "check" | "check_blue" | "cross" | "unknown"
  - `pro`: "check" | "check_blue" | "cross" | "unknown"
  - `enterprise`: "check" | "check_blue" | "cross" | "unknown"

## Plan Structure

The `plans` object contains arrays of features organized by plan:

- `starter`: Features available in Starter plan
- `plus`: Features available in Plus plan
- `pro`: Features available in Pro plan
- `enterprise`: Features available in Enterprise plan

Each plan feature includes:

- `name`: Feature name
- `category`: Category name
- `category_id`: Category ID
- `icon_type`: "check" | "check_blue"

## PHP Helper Functions

**File:** `v2/helpers/comparison-table-data.php`

### Main Functions

- `loadComparisonTableData()`: Load JSON data (cached)
- `getComparisonCategories()`: Get all categories
- `getComparisonCategory($id)`: Get category by ID
- `getComparisonFeaturesByCategory($id)`: Get features for category
- `getComparisonFeaturesByPlan($plan)`: Get features for plan
- `filterComparisonFeaturesBySearch($features, $term)`: Filter by search term
- `filterComparisonCategories($ids)`: Filter categories by IDs
- `filterComparisonDifferencesOnly($categories)`: Show only differences
- `getFeaturePlanAvailability($feature, $plan)`: Get availability status
- `isFeatureAvailableInPlan($feature, $plan)`: Check if available

## View Components

### Category View

**File:** `v2/sections/comparison-table-category-view.php`

Renders features organized by category with collapsible sections. Supports:

- Category filtering
- Search filtering
- Differences-only mode
- First category open by default

### Plan View

**File:** `v2/sections/comparison-table-plan-view.php`

Renders features organized by plan with collapsible sections. Shows:

- All features for each plan
- Category grouping within each plan
- Search filtering

## Filtering

### URL Parameters

- `search`: Text search term
- `categories`: Comma-separated category IDs
- `plans`: Comma-separated plan names
- `differences`: "1" to show only differences

### JavaScript Functions

- `updateComparisonFilters()`: Update URL with current filters
- `clearComparisonFilters()`: Reset all filters
- `initializeComparisonFilters()`: Set up filter event listeners

## Icon Types

- `check`: Gray checkmark (feature available)
- `check_blue`: Blue checkmark (feature available, highlighted for Pro)
- `cross`: Gray X (feature not available)
- `unknown`: Unknown status (should not occur)

## Usage Example

```php
require_once __DIR__ . '/../helpers/comparison-table-data.php';

// Get all categories
$categories = getComparisonCategories();

// Get features for a category
$features = getComparisonFeaturesByCategory('schichtplan');

// Get features for a plan
$features = getComparisonFeaturesByPlan('pro');

// Filter by search
$filtered = filterComparisonFeaturesBySearch($features, 'app');
```

## Data Extraction

**Script:** `scripts/extract-comparison-data.py`

Legacy tooling may have extracted from `v2/pages/static_pricing.php`; **live** matrix is maintained in `v2/data/comparison-table-data.json` for `static_pricing_new.php` (`/preise`).

**Usage:**

```bash
python3 scripts/extract-comparison-data.py
```

## Maintenance

To update comparison data for the live pricing page:

1. Edit `v2/data/comparison-table-data.json` (categories + per-feature `plans` matrix)
2. Validate JSON: `python3 -m json.tool v2/data/comparison-table-data.json`
3. Test both tabs (Funktionen pro Kategorie / pro Plan), filters, and „Nur Unterschiede“ on `/preise`
4. Optionally sync the denormalized `plans` block in the same file or remove it in a dedicated cleanup

Legacy extraction from `static_pricing.php` may still exist via `scripts/extract-comparison-data.py`; prefer direct JSON edits for `static_pricing_new.php`.