✝

Documentation

Liturgy Bot — Solution Design & Architecture

Version 8.0 · April 2026 · Status: Production

1. Overview

Liturgy Bot is a fully automated weekly pipeline that generates a Children's Liturgy of the Word document for a Catholic parish in the Diocese of Westminster. Every Saturday at 06:00 UTC, a Railway cron service fetches two source PDFs from diocesan websites, generates a formatted .docx document using the Anthropic API (Claude Opus 4.6 for reflections, Claude Sonnet 4 for supporting content), and emails it via the Brevo REST API to two catechists.

PlatformRailway (cron service, Hobby plan)
TriggerRailway cron — 0 6 * * 6 (Saturday 06:00 UTC)
RuntimeDocker container (Python 3.12-slim, ~25MB compressed, 42–48s execution)
AI ModelsClaude Opus 4.6 (reflection) + Claude Sonnet 4 (introduction, gospel summary)
EmailBrevo REST API, from bot@liturgybot.com
Codebase~6,200 lines · 46 files · 41 commits · 247 tests passing
First Automated RunSaturday 12 April 2026
Est. Annual Cost~£14 (Railway ~£8 + Anthropic API ~£6 + Brevo £0)

2. Source Authority Hierarchy

Westminster Diocese is the authoritative source for all readings and liturgical texts. The following hierarchy applies whenever sources conflict:

RankSourceAuthority
1Westminster Diocese PDFAuthoritative for readings, prayers, Gospel reference, creed, bidding prayers. Always overrides other sources.
2Adorers of the Blood of Christ PDFChildren's lectionary text and Gospel Acclamation verse. Westminster overrides on any conflict. Adorers' reflection is excluded.
3Calendar YAMLSeason rules, Gloria/Alleluia flags, song, file naming only. Gospel references are indicative and may be overridden at runtime.

Conflict Detection

After parsing both PDFs, the pipeline compares the Westminster Gospel reference against the YAML entry. If they differ, it uses Westminster's version, logs a warning, and sends a conflict notification email.

3. Pipeline Architecture

The pipeline runs as a Railway cron service with seven sequential stages, making three separate Anthropic API calls. Each stage is a separate Python module. The orchestrator (main.py) executes them in order with structured logging and error handling.

StageModulePurposeOutput
1calendar.pyResolve next Sunday, season rulesSunday dataclass
2fetcher.pyScrape landing pages, download PDFs2 PDF files
3parser.pyExtract text, split into sectionsParsed sections
4main.pyConflict detection (YAML vs Westminster)Validated gospel ref
5generator.py3 API calls: intro + reflection + summaryGeneratedContent
6assembler.pyBuild formatted Word document.docx file
7emailer.pySend email with attachmentEmail delivered

Pipeline Architecture Diagram

Seven-stage sequential pipeline with three Anthropic API calls

1. Calendarcalendar.py 2. Fetch PDFsfetcher.py 3. Parseparser.py 4. Validatemain.py 5. Generategenerator.py 6. Assembleassembler.py 7. Emailemailer.py External Services Westminster Diocesercdow.org.uk (PDF) Adorers of the Bloodadorers.org (PDF) Anthropic APIClaude Opus 4.6 + Sonnet 4 Brevo REST APIapi.brevo.com (HTTPS) Anthropic API Calls (Stage 5) IntroductionClaude Sonnet 4512 max tokens ReflectionClaude Opus 4.64,096 max tokens Gospel SummaryClaude Sonnet 4128 max tokens Data Flow Summary YAML CalendarSeason + rules 2 Source PDFsWestminster + Adorers Parsed SectionsDict of content AI ContentIntro + Reflection .docx File14-row table Emailvia Brevo API Liturgy Bot v8.0 — Pipeline Architecture — April 2026

4. AI Model Strategy

The pipeline makes three separate Anthropic API calls, using two different models chosen for their distinct strengths:

CallModelMax TokensPurpose
IntroductionClaude Sonnet 45122–3 sentence introduction linking to previous weeks
ReflectionClaude Opus 4.64,096Conversation-guide reflection: questions woven through the Gospel story
Gospel SummaryClaude Sonnet 4128One-sentence summary for the email body
Why two models? Sonnet 4 produces essay-like reflections that talk at children rather than with them. Opus 4.6 has the depth and restraint for the Socratic, conversation-guide format: grounding children in the story through sequential questions, letting them discover meaning rather than being told it. The quality difference was immediately apparent in A/B testing. Cost impact is ~£10/year additional.

5. Document Structure

Every generated document follows a fixed 14-row single-column table format:

RowSectionContent Source
1Prayer for Holy Spirit guidanceStatic text (italic)
2DismissalStatic
3Sign of the CrossStatic
4Light the CandlesStatic
5IntroductionAI-generated (Sonnet 4)
6Saying SorryWestminster PDF
7Gloria / Seasonal SubstituteCalendar engine
8Opening PrayerWestminster PDF
9First ReadingHeading only
10Gospel AcclamationAdorers (verse) + Calendar (frame) + Westminster (ref)
11ReflectionAI-generated (Opus 4.6)
12CreedWestminster PDF
13SongCalendar engine
14Bidding PrayersWestminster PDF + standard closing

6. Module Detail

ModulePurposeLinesTests
calendar.pyLiturgical calendar engine, Year A YAML data, Sunday dataclass23540
fetcher.pyPDF fetch via landing page scrape, CL availability check29632
parser.pyPDF text extraction (pymupdf), regex section parsing34945
generator.pyAnthropic API client — 3 calls (intro, reflection, summary)36026
assembler.pyDOCX template assembler — 14-row table33822
emailer.pyBrevo REST API sender + notification emails~28050
main.pyPipeline orchestrator with CLI, conflict detection19413

7. Infrastructure

Infrastructure Diagram

Railway cron service with Brevo REST API email delivery

GitHub git push Railway Cron Trigger0 6 * * 6 Docker ContainerPython 3.12-slim Data Sources Westminster Diocesercdow.org.uk — PDF download Adorers of the Bloodadorers.org — PDF download Anthropic APIOpus 4.6 (reflection)Sonnet 4 (intro + summary) Output Pipeline .docx Assemblypython-docx • 14-row table Brevo REST APIapi.brevo.com (HTTPS) .docx attached Recipients2 catechistsfrom bot@liturgybot.com Notification Emails Error NotificationOn pipeline failure Conflict NotificationYAML vs Westminster No-CL Notificatione.g. Easter Sunday Liturgy EmailWeekly .docx delivery Liturgy Bot v8.0 — Infrastructure — April 2026

Infrastructure Migration

The bot was originally deployed on Google Cloud Platform (Cloud Run Job + Cloud Scheduler + Secret Manager + Gmail API). This was abandoned due to Google's impractical OAuth verification process for small internal tools. GCP resources have been deleted.

ComponentBefore (GCP)After (Railway + Brevo)
RuntimeCloud Run JobRailway cron service
SchedulerCloud SchedulerRailway cron
EmailGmail API (OAuth)Brevo REST API (HTTPS)
From addressPersonal Gmailbot@liturgybot.com
Deploy triggerManual scriptAuto-deploy on git push
VerificationGCP OAuth (abandoned)None needed
Annual cost~£15~£14

8. Dependencies

PackageVersionPurpose
anthropic≥0.42.0Claude API client (Opus 4.6 + Sonnet 4)
beautifulsoup4≥4.12.0HTML scraping
pymupdf≥1.25.0PDF text extraction
python-docx≥1.1.0Word document generation
pyyaml≥6.0YAML calendar parsing
requests≥2.32.0HTTP requests + Brevo REST API

9. Test Suite

247 tests, all passing.

ModuleTestsKey Coverage
test_calendar.py40Calendar engine, season rules, lookups, edge cases
test_fetcher.py32PDF fetch, scraping, date matching, error handling
test_parser.py45Westminster & Adorers parsing, gospel ref regex
test_generator.py26Three-call architecture, model selection, response parsing
test_assembler.py22All 14 rows, season-dependent content, file naming
test_emailer.py50Brevo REST API calls, all four email types, error handling
test_main.py13Pipeline orchestration, conflict detection, CLI
Integration (skipped)12End-to-end with real PDFs (require network access)

10. Running Costs

ComponentEstimated Annual Cost
Railway (shared Hobby plan, proportional usage)~£8
Anthropic API: Opus 4.6 reflection~£5
Anthropic API: Sonnet 4 intro + summary~£1
Brevo REST API (free tier)£0
GitHub Pages (website hosting)£0
Total~£14/year