church-api/HYMNARIUM_API_DOCUMENTATION.md

# Adventist Hymnarium API Documentation

## Overview

The Church API includes a comprehensive hymnal system supporting both the 1985 Seventh-day Adventist Hymnal and the 1941 Church Hymnal. The system provides intelligent search capabilities, complete hymn content, thematic organization, and responsive readings.

## Database Structure

### Migration & Data Standardization

- **Migration Date**: August 27, 2025
- **Total Hymns**: 1,398 hymns (695 from 1985 + 703 from 1941)
- **Data Source**: SQLite `hymnarium.db` migrated to PostgreSQL
- **Format Standardization**: Both hymnals now use consistent numbered verse formatting (1., 2., 3., etc.)

The 1941 hymnal content was automatically converted from its original format to match the 1985 numbered verse structure for consistency.

### Database Schema

#### Hymnals Table
```sql
- id: UUID (primary key)
- name: VARCHAR(100) - Display name
- code: VARCHAR(50) - Unique identifier (sda-1985, sda-1941) 
- description: TEXT
- year: INTEGER
- language: VARCHAR(10) - Default 'en'
- is_active: BOOLEAN
```

#### Hymns Table
```sql
- id: UUID (primary key)
- hymnal_id: UUID (foreign key to hymnals)
- number: INTEGER - Hymn number within that hymnal
- title: VARCHAR(255)
- content: TEXT - Full hymn text with standardized verse numbering
- is_favorite: BOOLEAN
- UNIQUE(hymnal_id, number)
```

#### Additional Tables
- **thematic_lists**: Theme categories (Worship, Trinity, etc.)
- **thematic_ambits**: Hymn number ranges within themes
- **responsive_readings**: Numbered 696-920 (from 1985 hymnal)

## API Endpoints

### Base URL
```
http://localhost:3002/api
```

### Hymnals

#### List All Hymnals
```http
GET /hymnals
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": "39484599-c028-4c19-8c9d-2b174f13efa6",
      "name": "Seventh-day Adventist Hymnal",
      "code": "sda-1985",
      "description": "The current SDA Church Hymnal published in 1985",
      "year": 1985,
      "language": "en",
      "is_active": true
    },
    {
      "id": "698045d8-231c-4bd5-8fef-8af0deab8cb4", 
      "name": "Church Hymnal",
      "code": "sda-1941",
      "description": "The older SDA Church Hymnal published in 1941",
      "year": 1941,
      "language": "en",
      "is_active": true
    }
  ]
}
```

#### Get Hymnal by Code
```http
GET /hymnals/code/{code}
```

**Example:** `GET /hymnals/code/sda-1985`

### Hymns

#### List All Hymns from a Specific Hymnal
```http
GET /hymns/search?hymnal={hymnal_code}&per_page=1000
```

**Example:** `GET /hymns/search?hymnal=sda-1985&per_page=1000`

This returns all 695 hymns from the 1985 hymnal or all 703 hymns from the 1941 hymnal.

#### Get Specific Hymn
```http
GET /hymns/{hymnal_code}/{number}
```

**Example:** `GET /hymns/sda-1985/1`

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "35ab3b49-e49b-470b-a104-c2632089af49",
    "hymnal_id": "39484599-c028-4c19-8c9d-2b174f13efa6",
    "hymnal_name": "Seventh-day Adventist Hymnal",
    "hymnal_code": "sda-1985",
    "hymnal_year": 1985,
    "number": 1,
    "title": "Praise to the Lord",
    "content": "1.\nPraise to the Lord, the Almighty, the King of creation!\nO my soul, praise Him, for He is thy health and salvation!\n...",
    "is_favorite": false
  }
}
```

### Intelligent Search System

#### Search Hymns
```http
GET /hymns/search?q={search_term}&hymnal={hymnal_code}&per_page={limit}
```

**Parameters:**
- `q`: Search term (required for text searches)
- `hymnal`: Filter by hymnal code (sda-1985 or sda-1941) - **RECOMMENDED**
- `per_page`: Results limit (default: 20)
- `page`: Page number for pagination

#### Search Features & Scoring

The search system uses intelligent scoring (higher scores = better matches):

**Search Types Supported:**
1. **Hymn Numbers**: `123`, `hymn 123`, `no. 123`, `number 123`
2. **Exact Titles**: `Amazing Grace`
3. **Multi-word Phrases**: `friend jesus` → finds "What a Friend We Have in Jesus"
4. **Partial Titles**: `praise lord` → finds "Praise to the Lord"
5. **Lyrics Content**: `how sweet the sound` → finds Amazing Grace
6. **Any Word Order**: `jesus friend` and `friend jesus` both work

**Scoring System:**
- **1600 points**: Exact hymn number match
- **1500 points**: Exact title match
- **1200 points**: Title starts with search term
- **800 points**: Title contains exact phrase
- **700 points**: All search words found in title (multi-word bonus)
- **650 points**: 3+ search words found in title
- **600 points**: First line contains phrase
- **400 points**: Any search word in title
- **300 points**: Content contains exact phrase
- **200 points**: Multi-word match in content
- **100 points**: Any search word in content

#### Search Examples

**Single Hymnal Search (Recommended):**
```http
GET /hymns/search?q=amazing%20grace&hymnal=sda-1985
```

**Multi-word Search:**
```http
GET /hymns/search?q=friend%20jesus&hymnal=sda-1985
```

**Number Search:**
```http
GET /hymns/search?q=123&hymnal=sda-1941
```

**Cross-Hymnal Search (if needed):**
```http
GET /hymns/search?q=amazing%20grace
```

### Thematic Organization

#### Get Themes for a Hymnal
```http
GET /hymnals/code/{hymnal_code}/themes
```

**Example:** `GET /hymnals/code/sda-1985/themes`

Returns thematic lists with their hymn number ranges (ambits).

### Responsive Readings

#### List Responsive Readings
```http
GET /responsive-readings?per_page=225
```

#### Get Specific Responsive Reading
```http
GET /responsive-readings/{number}
```

**Example:** `GET /responsive-readings/696`

**Note**: Responsive readings are numbered 696-920 (from the 1985 hymnal section).

## Frontend Integration Guide

### Recommended Usage Pattern

1. **Hymnal Selection**: Let users choose between sda-1985 or sda-1941
2. **Scoped Searches**: Always include `hymnal={selected_hymnal}` parameter
3. **Search URL Pattern**: `/api/hymns/search?q={searchTerm}&hymnal={selectedHymnal}`

### Example Frontend Logic
```javascript
const selectedHymnal = 'sda-1985'; // or 'sda-1941'
const searchTerm = 'friend jesus';

const searchUrl = `/api/hymns/search?q=${encodeURIComponent(searchTerm)}&hymnal=${selectedHymnal}&per_page=20`;

// This returns only hymns from the selected hymnal with intelligent scoring
```

### Content Format

All hymn content uses standardized formatting:
```text
1.
[First verse content]

2. 
[Second verse content]

3.
[Third verse content]
```

Both 1985 and 1941 hymnals now use this consistent format.

## Technical Implementation

### Search Intelligence

The backend handles all search complexity including:
- **Multi-word term splitting**
- **Phrase detection**
- **Word order independence**
- **Relevance scoring**
- **Performance optimization**

### Database Optimizations

- Full-text search indexes on titles and content
- Optimized queries with CTEs for scoring
- Proper foreign key relationships
- Pagination support

### Error Handling

All endpoints return standardized responses:
```json
{
  "success": boolean,
  "data": any,
  "message": string | null
}
```

## Migration Details

### Data Processing

1. **Source**: SQLite `hymnarium.db` with 1,398 hymns
2. **Processing**: Python migration script with intelligent format conversion
3. **Standardization**: 1941 hymnal verses automatically numbered to match 1985 format
4. **Validation**: All hymns migrated successfully with proper relationships

### Migration Script Location
```
/opt/rtsda/church-api/migrate_hymnal_data.py
```

## Performance Notes

- **Search Performance**: Optimized with PostgreSQL indexes and scoring CTEs
- **Database Size**: ~1,400 hymns with full content searchable
- **Response Times**: Sub-second search responses
- **Scalability**: Ready for additional hymnals or languages

## Development Notes

### Code Organization
- **Search Logic**: `/src/services/hymnal_search.rs`
- **Main Service**: `/src/services/hymnal.rs` 
- **Handlers**: `/src/handlers/hymnal.rs`
- **Models**: Defined in `/src/models.rs`

### Future Enhancements
- Fuzzy matching for typos
- Additional hymnal languages
- Advanced search filters
- Bookmark/favorites system
- Audio integration support

---

**Last Updated**: August 27, 2025  
**API Version**: 1.0  
**Database**: PostgreSQL with 1,398 standardized hymns