ponomar-pwa/.ai-specs/PROJECT_CONTEXT.md

Project Context for AI Agents

Quick Project Overview

Ponomar is a Progressive Web App for Orthodox Church calendar, liturgical services, and Bible readings.

• Technology: TypeScript + Vite + Tailwind CSS v4
• Data: JSON-based liturgical data organized by language (en, cu, ru)
• Architecture: Client-side PWA with static JSON data, no backend database
• Core Functionality: Calendar display, service assembly, Bible reading, saint lives, astronomy

Key Architectural Patterns

Data Organization

• Language-based structure: static/data/{lang}/ (en, cu, ru)
• Bundle system: menaion-bundles, lives bundles (month-prefixed + misc split), service templates
• File routing: CIds with 01-12 prefix → month files, else misc/{first-digit}.json

Language Model (UI vs. Content)

• UI strings: en/ru/cu via getTranslations(); completeness checked by validate-i18n.ts
• Service language (serviceLang in service-view.ts): en → en, cu → cu, ru → cu — a Russian interface intentionally renders services in Church Slavonic
• Service content fallback chain: serviceLang → cu → shared (texts, prayers, headers, lives, octoechos, templates); ru/services/ carries only var/
• Scripture inside services follows the service language: en → en/bible/kjv, cu (and ru) → cu/bible/elis
• Bible reader tab is independent: 13 translations (incl. ru/bible/synod), any UI language
• Fonts: the Slavonic font setting applies to liturgical text for cu and ru (getFontClass())
• Calendar authority: cu/menaion-bundle.json; {lang}-menaion-bundle.json overrides

Core Scripts

• convert-services.ts — Service XML to JSON conversion
• enrich-lives.ts — Fuzzy matching and enrichment pipeline (Chetyi-Minei + Bulgakov)
• validate-data.ts — Main validator
• convert-bulgakov.ts — Bulgakov's Desktop Book EPUB to JSON conversion

Recent Work Context

Completed Enrichment

• Chetyi-Minei import: 1154 chapters processed, 1190 lives enriched
• Bulgakov import: 332 entries from "Настольная книга" Menaion section, 13 new lives enriched
• Manual fixes: 224 manual corrections in enrich-lives.ts (64 Minei + 9 Bulgakov + others)
• Bundle fixes: 868 Иаков Боровицкий corrected from 05-22 to 10-23
• Coverage: 1203/3046 lives have texts (sources: Chetyi-Minei + Bulgakov)

Validation Status

• All data files validated
• TypeScript compiles cleanly
• Build succeeds without errors

Critical Invariants

• Never overwrite existing life.text — enrichment only fills empty entries
• Bulgakov is secondary source — fills gaps, never overrides Minei
• File routing is strict: CId prefix determines file location
• Bundle CIds must exist: Menaion CIds require corresponding lives entries
• Static data is tracked: static/data/ in git (except scripts/output/minei.json)
• Validation must pass: Changes must pass tsc --noEmit, npm run build
• Content policies: service/Bible texts are sourced (never translated), cu text is verbatim (no normalisation/latinisation), service assembly follows the Typicon — see .ai-specs/WORKING_POLICIES.md ("Liturgical Content Policies")

Key Script Quick Reference

# Development
npm run dev              # Start dev server
npm run build            # Production build

# Validation
npx tsc --noEmit                 # Type checking
npm run build                     # Build verification
npx tsx scripts/validate-data.ts  # Main validator

# Enrichment (Minei)
npx tsx scripts/enrich-lives.ts              # Dry run
npx tsx scripts/enrich-lives.ts --write       # Apply

# Enrichment (Bulgakov)
npx tsx scripts/enrich-lives.ts --bulgakov    # Dry run
npx tsx scripts/enrich-lives.ts --bulgakov --write

File Structure Highlights

src/
├── core/           # Domain logic (calendar, paschalion, service assembly, astronomy)
├── ui/             # View components
└── main.ts         # Entry point

scripts/
├── convert-*.ts    # XML/EPUB → JSON conversion pipeline
├── validate-*.ts   # Comprehensive validation suite
└── enrich-lives.ts # Enrichment with manual fixes (Minei + Bulgakov)

static/data/
├── cu/             # Church Slavonic (authoritative calendar)
├── ru/             # Russian (enriched lives)
├── en/             # English (enriched lives + service texts)
└── shared/         # Cross-language resources (calendar, lives index, parimii)

Important Notes

Pipeline Dependencies

• Chetyi-Minei source: EPUB conversion requires convert-minei.ts
• Bulgakov source: EPUB conversion requires convert-bulgakov.ts
• Enrichment workflow: Requires minei.json + bulgakov.json + menaion-bundle.json
• Validation chain: Each commit must pass typecheck → build

File System Constraints

• scripts/output/minei.json is gitignored (33MB source file)
• scripts/output/bulgakov.json is gitignored
• static/data/ is fully tracked in git
• Lives files: month files (01.json-12.json) + misc split (misc/0.json-misc/9.json)

Current State

• Total CIds: 3046
• Lives with text: 1203 (Chetyi-Minei + Bulgakov)
• Unmatched Minei: 27 (floor: narratives, no-target, already-filled)
• Unmatched Bulgakov: 121 (all no recoverable targets)
• Latest enrichment commits: e32d787 (Bulgakov), c342a5b (orthography), 08950cd (64 fixes)

Documentation Reference

• DATA_EN.md — Detailed technical specifications (English)
• DATA_RUS.md — Complete documentation in Russian
• README.md — Project overview and getting started