# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a structured JSON data repository for Islamic sholawat (prayers/praises) with multilingual support. The data is distributed via CDN (jsDelivr) and npm package (`sholawat-json` on npm, MIT license).

## Commands

```bash
# Validate all JSON files against schemas (Go validator)
cd validator && go run main.go

# Or use the precompiled binary (no Go required)
./validator/validator
```

The validator has **no command-line flags** — all paths are hardcoded. It reads `sholawat/sholawat.json` to discover files, validates each against its declared schema, and **reports orphan files** (JSON files on disk not registered in `sholawat/sholawat.json`). Validation runs concurrently across all sources.

All JSON changes must pass validation before committing. CI enforces this automatically (see CI/CD below).

## CI/CD

Two GitHub Actions workflows (in `.github/workflows/`):

- **`validate.yml`**: Runs the Go validator on every push to `master` and every PR touching `sholawat/**` or `schemas/**`
- **`publish.yml`**: On GitHub release, runs the validator, bumps `package.json` version from the tag, and publishes to npm

## Architecture

### Three Sholawat Types

1. **Fasl-based** (`burdah`, `diba`, `simtudduror`): Chapter-based collections stored in numbered files under `sholawat/{type}/{source}/fasl/`. Has a `number` field (integer) for chapter ordering.

   Two sub-patterns:
   - **Flat text** (`burdah`): Uses a `text` object with numeric verse keys directly
   - **Sections** (`diba`, `simtudduror`): Uses a `sections` object, where each section has a `type` from enum `["rawi", "bari", "closing"]` and a nested `text`

2. **Tunggal (Single)**: Standalone prayers in `sholawat/tunggal/{name}.json`. No `number` field.

3. **Suluk**: Special prayers in `sholawat/suluk/{name}.json`. Same structure as tunggal but may include `author` and `transmitter` fields.

### Data Structure

- Verse keys are **numeric strings** (`"1"`, `"2"`, not integers)
- Language codes follow **ISO 639-1** (`id`, `en`, `ar`)
- Arabic text is required; Latin transliteration is nullable
- `last_updated` uses **ISO 8601 format** (`YYYY-MM-DD`)

### Registry

`sholawat/sholawat.json` is the centralized registry mapping all files to their schemas. Every JSON data file must be listed here — the validator flags unregistered files as orphans and CI will fail. CDN URLs are derived from file paths in this registry.

Note: `source_name` in the registry (e.g., `"nu-online"`) uses lowercase hyphens and is a logical identifier. The corresponding `path_files` directory name may use underscores (e.g., `nu_online/`).

### Schemas

Located in `schemas/`. All use JSON Schema 2020-12. Naming pattern:
`{type}_{descriptor}_v{major}.{minor}.schema.json`

Schema changes require a version bump — never modify an existing schema without bumping the version. Every data file using the old schema must be updated to reference the new one.

**Active schemas in use:**
| Schema | Used by |
|--------|---------|
| `burdah_fasl_v1.0` | nu-online, dalail-al-khairat |
| `burdah_fasl_v1.1` | minhaj-ul-quran, maktabah-al-mihrab |
| `diba_fasl_v1.0` | nu-online |
| `simtudduror_fasl_v1.0` | nu-online |
| `suluk_v1.1` | general |
| `sholawat_tunggal_v1.1` | general |

`suluk_v1.0` and `sholawat_tunggal_v1.0` exist on disk but are unused (all content migrated to v1.1).

### Field Conventions

| Field | Availability | Description |
|-------|-------------|-------------|
| `source` | All types | Source identifier; nullable in v1.1 tunggal/suluk |
| `author` | v1.1 tunggal/suluk only | Original author (optional) |
| `transmitter` | v1.1 tunggal/suluk only | Transmission chain (optional) |
| `translator` | v1.1 translation entries | Translation attribution |
| `muqaddimah` | v1.1 burdah/diba translation entries | Chapter introduction text |

**Source naming:** Use lowercase hyphenated format. Examples: `"nu-online"`, `"minhaj-ul-quran"`, `"duta-islam"`

**Schema version differences (v1.0 → v1.1):**
- v1.1 adds optional `author`, `transmitter`, `muqaddimah`, `translator` fields
- v1.1 makes `source` nullable in tunggal/suluk schemas
- `diba_fasl_v1.0` is the **only** schema where `translations` is required (`"type": "object"`, not `["object","null"]`)

## Critical Rules

- **Register every new JSON file** in `sholawat/sholawat.json` or it will be flagged as orphan
- **Validate before commit**: Run `cd validator && go run main.go`
- **Never modify schemas without version bump** — all files referencing the old schema must be updated
- **Numeric string keys required** (`"1"` not `1`)
- **CDN paths derived from** file paths in `sholawat/sholawat.json`
- **Never alter Arabic text** without user-provided corrections

## File Navigation

- **Registry**: `sholawat/sholawat.json`
- **Schema documentation**: `schemas/SCHEMA_README.md`
- **Validator source**: `validator/main.go` (separate Go module, `go.mod` inside `validator/`)
- **AI instructions**: `.github/instructions/` and `.github/copilot-instructions.md` (gitignored, local-only)