revelation-bible

Domain-driven Bible data types and port traits for Rust applications.

Table of Contents

• Overview
• Features
• Installation
• Architecture
• Domain Types
• Port Traits
• Usage Examples
• Feature Flags
• Code Coverage
• License

Overview

revelation-bible provides a clean, type-safe foundation for building Bible-related applications in Rust. Following hexagonal architecture principles, it separates domain logic from infrastructure concerns:

• Domain types define the core data structures (books, verses, cross-references)
• Port traits define interfaces for data access without coupling to specific implementations

This allows you to build applications that work with any database, API, or file format by simply implementing the port traits.

Features

• Complete Bible Model: All 66 books, chapters, verses with full metadata
• Cross-References: Link related passages with relevance scoring
• Symphony/Concordance: Word-based search with occurrence tracking
• Reading Plans: Daily reading schedules with user responses
• Section Headings: Pericope support for navigation
• Multi-language: Built-in support for English and Russian names
• Type-safe: Strong typing prevents invalid references at compile time
• Zero-cost Abstractions: Optional features add no overhead when disabled

Installation

Add to your Cargo.toml:

[dependencies]
revelation-bible = "0.1"

With specific features:

[dependencies]
revelation-bible = { version = "0.1", features = ["db", "api", "backend"] }

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Your Application                       │
├─────────────────────────────────────────────────────────────┤
│                    revelation-bible                         │
│  ┌─────────────────────┐    ┌─────────────────────────────┐ │
│  │    Domain Types     │    │       Port Traits           │ │
│  │  ─────────────────  │    │  ─────────────────────────  │ │
│  │  Book, Verse        │    │  BibleRepository            │ │
│  │  CrossReference     │◄───│  BibleSearch                │ │
│  │  SearchResult       │    │  BibleCrossReference        │ │
│  │  DailyReading       │    │  ReadingPlan                │ │
│  └─────────────────────┘    └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐    ┌──────────┐
        │ Postgres │   │   REST   │    │   JSON   │
        │ Adapter  │   │   API    │    │  Files   │
        └──────────┘   └──────────┘    └──────────┘

Domain Types

Core Types

Search & Cross-References

Reading Plan

Port Traits

Port traits define the interface for data access. Implement these in your adapters:

BibleRepository

Core CRUD operations for Bible data:

pub trait BibleRepository: Send + Sync {
    fn get_books(&self) -> impl Future<Output = AppResult<Vec<Book>>> + Send;
    fn get_book(&self, id: i16) -> impl Future<Output = AppResult<Option<Book>>> + Send;
    fn get_chapter(&self, book_id: i16, chapter: i16) -> impl Future<Output = AppResult<Vec<Verse>>> + Send;
    fn get_verse(&self, book_id: i16, chapter: i16, verse: i16) -> impl Future<Output = AppResult<Option<Verse>>> + Send;
    // ... more methods
}

BibleSearch

Full-text search and symphony (concordance):

pub trait BibleSearch: Send + Sync {
    fn search(&self, query: &str, limit: i64) -> impl Future<Output = AppResult<Vec<SearchResult>>> + Send;
    fn symphony(&self, word: &str, limit: i64) -> impl Future<Output = AppResult<Vec<SearchResult>>> + Send;
    fn word_count(&self, word: &str) -> impl Future<Output = AppResult<i64>> + Send;
}

BibleCrossReference

Cross-reference lookups:

pub trait BibleCrossReference: Send + Sync {
    fn get_cross_references(&self, book_id: i16, chapter: i16, verse: i16, limit: i64)
        -> impl Future<Output = AppResult<Vec<CrossReferenceExpanded>>> + Send;
    fn get_reverse_references(&self, book_id: i16, chapter: i16, verse: i16, limit: i64)
        -> impl Future<Output = AppResult<Vec<CrossReferenceExpanded>>> + Send;
    fn get_chapter_references(&self, book_id: i16, chapter: i16)
        -> impl Future<Output = AppResult<Vec<CrossReference>>> + Send;
}

ReadingPlan

Daily reading plan operations:

pub trait ReadingPlan: Send + Sync {
    fn get_today(&self) -> impl Future<Output = AppResult<Option<DailyReading>>> + Send;
    fn get_for_date(&self, date: NaiveDate) -> impl Future<Output = AppResult<Option<DailyReading>>> + Send;
    fn add_response(&self, user_id: Uuid, daily_reading_id: Uuid, content: &str)
        -> impl Future<Output = AppResult<Uuid>> + Send;
}

Usage Examples

Basic Usage

use revelation_bible::{Book, Verse, Testament};

// Create a book reference
let genesis = Book {
    id: 1,
    name: "Genesis".into(),
    name_ru: "Бытие".into(),
    abbreviation: "Gen".into(),
    testament: Testament::Old,
    chapters_count: 50,
};

// Work with verses
let verse = Verse {
    id: 1001,
    book_id: 43,  // John
    chapter: 3,
    verse: 16,
    text: "For God so loved the world...".into(),
};

Cross-References

use revelation_bible::{VerseRef, CrossReference};

// Single verse reference
let john_3_16 = VerseRef::single(43, 3, 16);

// Verse range
let romans_5_1_5 = VerseRef::range(45, 5, 1, 5);

// Cross-reference with relevance weight
let cross_ref = CrossReference {
    id: 1,
    from: john_3_16,
    to: romans_5_1_5,
    weight: Some(850),  // Higher = more relevant
};

Implementing a Port

use revelation_bible::ports::BibleRepository;
use revelation_bible::{Book, Verse, ChapterInfo, Pericope, Testament};
use masterror::AppResult;

struct MyBibleAdapter {
    // your database connection
}

impl BibleRepository for MyBibleAdapter {
    async fn get_books(&self) -> AppResult<Vec<Book>> {
        // Your implementation
        todo!()
    }

    async fn get_book(&self, id: i16) -> AppResult<Option<Book>> {
        // Your implementation
        todo!()
    }

    // ... implement other methods
}

Feature Flags

Feature Combinations

# Frontend/WASM - minimal, just types
revelation-bible = "0.1"

# Backend with PostgreSQL
revelation-bible = { version = "0.1", features = ["db", "backend"] }

# Full backend with OpenAPI docs
revelation-bible = { version = "0.1", features = ["db", "api", "backend"] }

Code Coverage

We maintain high test coverage to ensure reliability. Below are visual representations of our codebase coverage:

Sunburst

The inner circle represents the entire project. Moving outward: folders, then individual files. Size = number of statements, color = coverage percentage.

Grid

Each block represents a file. Size = number of statements, color = coverage level (green = high, red = low).

Icicle

Hierarchical view: top = entire project, descending through folders to individual files. Size and color represent statements and coverage.

Dependencies

Related Crates

• revelation-server - PostgreSQL adapters and REST API
• revelation-user - User domain types
• revelation-songbook - Hymnal domain types

License

This project is licensed under the MIT License - see the LICENSE file for details.

Part of the Revelation Project - Building tools for Bible study and worship.