From b582c12c04bcedcd1785ca4a2d859d43cd34261d Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 23 Nov 2025 00:37:02 -0500 Subject: [PATCH] Completely rewrite README with comprehensive documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaced merge-conflicted, duplicative README with clean, professional documentation from the ground up. New structure includes: - Clear project description and live site link - Comprehensive feature inventory organized by category - All study guides, biblical resources, and tools documented - Complete tech stack breakdown - Installation and deployment instructions - Project structure diagram - Contributing guidelines and roadmap - No merge conflicts, no duplicates, no emojis The README now accurately reflects the full scope of the platform and provides clear onboarding for developers, contributors, and users. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 351 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 211 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index 182e562..324a11d 100644 --- a/README.md +++ b/README.md @@ -1,182 +1,253 @@ # KJV Study -A web application for studying the King James Bible with AI-powered commentary and insights. +A comprehensive web application for deep study of the King James Bible, featuring original language tools, extensive theological resources, and classical scholarly presentation. + +**Live Site:** [kjvstudy.fly.dev](https://kjvstudy.fly.dev) ## Features -- Browse and search King James Bible verses -- **Study Guides** - Comprehensive Bible study guides covering foundational Christian truths, character development, and biblical themes -- **Verse of the Day** - Daily Scripture verses with reflection questions and sharing capabilities -- AI-powered biblical commentary and insights -- Clean, responsive web interface -- Fast verse lookup and navigation +### Bible Reading & Navigation +- **Complete KJV Text** - All 66 books, 1,189 chapters, 31,102 verses +- **Fast Search** - Full-text search with concordance functionality +- **Cross-References** - Comprehensive verse cross-referencing throughout Scripture +- **Verse Linking** - Automatic URL generation for easy sharing and bookmarking +- **Random Verse** - Discover Scripture serendipitously +- **Verse of the Day** - Daily curated verses with reflection questions + +### Study Tools + +#### Interlinear Bible +- Greek and Hebrew original language texts +- Word-by-word translation analysis +- Strong's concordance numbers +- Etymology and root word exploration +- Morphological tagging + +#### Study Guides +Comprehensive 8-section guides with extensive Scripture references: +- **The Gospel Message** - Nature of gospel, Christ's atonement, repentance & faith +- **Salvation by Grace** - Sin, penalty, grace, justification, eternal security +- **New Believer's Guide** - Foundational truths for new Christians +- **Fruits of the Spirit** - Source, cultivation, and evidence of spiritual fruit +- **Prayer & Faith** - Nature of prayer, biblical faith, growing in both +- **Christian Living** - Holiness, separation, stewardship, perseverance +- **God's Love** - Essential nature, covenant faithfulness, responding to love +- **Hope & Comfort** - God as refuge, resurrection hope, blessed hope +- **Wisdom & Guidance** - Fear of the Lord, discerning God's will, godly counsel + +#### Biblical Resources + +**People & Characters:** +- The Twelve Apostles - Detailed profiles with biblical accounts +- Women of the Bible - Key female figures and their significance +- Biblical Prophets - Major and minor prophets with historical context +- Biblical Angels - Angelic beings and their roles + +**Themes & Topics:** +- Parables of Jesus - Complete collection with interpretation +- Names of God - Revealing God's character through His names +- The Tetragrammaton - Deep dive into YHWH +- Biblical Covenants - Adamic, Noahic, Abrahamic, Mosaic, Davidic, New +- Fruits of the Spirit - Greek word studies and theological exposition +- Biblical Festivals - Passover, Pentecost, Tabernacles, and more +- Topical Index - Scripture organized by theme and subtopic + +**Historical Context:** +- Biblical Timeline - From Creation through the early Church +- Biblical Maps - Geographic context for biblical narratives +- Family Tree - Genealogies from Adam through biblical history with searchable lineages + +### Design & User Experience + +**Tufte CSS Styling:** +- Classical typography with serif fonts for optimal readability +- Sidenotes and margin notes for supplementary information +- High contrast and generous white space +- Responsive design that adapts to all screen sizes + +**Performance:** +- Aggressive caching for instant page loads +- Optimized for Fly.io deployment +- Always-on configuration eliminates cold starts +- Lazy loading of interlinear data + +**Accessibility:** +- Semantic HTML structure +- Clear heading hierarchy +- Keyboard navigation support +- High contrast text + +## Tech Stack + +**Backend:** +- **FastAPI** - Modern, high-performance Python web framework +- **Python 3.13** - Latest Python with performance improvements +- **biblepy** - KJV Bible text library +- **Jinja2** - Server-side templating with custom filters + +**Frontend:** +- **Tufte CSS** - Edward Tufte-inspired classical design +- **Vanilla JavaScript** - Minimal client-side code for enhanced functionality +- **Semantic HTML** - Accessible, well-structured markup + +**Infrastructure:** +- **Docker** - Containerized deployment +- **Fly.io** - Production hosting with global CDN +- **uv** - Fast Python package management ## Installation -1. Clone the repository -2. Install dependencies: +### Prerequisites +- Python 3.13 or higher +- [uv](https://github.com/astral-sh/uv) package manager + +### Local Development + +1. **Clone the repository** + ```bash + git clone https://github.com/kennethreitz/kjvstudy.org.git + cd kjvstudy.org + ``` + +2. **Install dependencies** ```bash uv sync ``` -## Usage +3. **Run the development server** + ```bash + uv run kjvstudy-org + ``` + +4. **Open your browser** + ``` + http://localhost:8000 + ``` + +### Docker Development -Run the development server: -```bash -uv run kjvstudy-org -``` - -The application will be available at http://localhost:8000 - -## Docker - -Build and run with Docker: ```bash +# Build the image docker build -t kjvstudy . + +# Run the container docker run -p 8000:8000 kjvstudy + +# Or use docker-compose +docker compose up ``` -## Requirements +## Deployment -- Python 3.13+ -- FastAPI -- biblepy +### Fly.io Deployment -## License +The application is optimized for Fly.io with: +- 2GB RAM, shared CPU (2 cores) +- Always-on configuration (min 1 machine) +- Preloaded interlinear data for fast responses +- Health checks and automatic recovery -See LICENSE file for details. - - - -======= - - -## New Features - -### Study Guides -Access comprehensive Bible study guides at `/study-guides` covering: -- **Foundational Studies**: New Believer's Guide, Salvation by Grace, The Gospel Message -- **Character & Living**: Fruits of the Spirit, Prayer & Faith, Christian Living -- **Biblical Themes**: God's Love, Hope & Comfort, Wisdom & Guidance - -Each study guide includes: -- Scripture references with full text -- Study notes and practical applications -- Reflection questions for deeper understanding - -### Verse of the Day -Visit `/verse-of-the-day` for: -- Daily Scripture verses from a curated collection -- Reflection questions for meditation -- Easy sharing capabilities -- Links to read the full chapter or book -- Integrated with the homepage for daily inspiration - -## Docker - -Build and run with Docker: ```bash -docker build -t kjvstudy . -docker run -p 8000:8000 kjvstudy +# Install Fly CLI +curl -L https://fly.io/install.sh | sh + +# Login to Fly +fly auth login + +# Deploy +fly deploy + +# View logs +fly logs + +# SSH into machine +fly ssh console ``` -## Requirements +### Environment Variables -- Python 3.13+ -- FastAPI -- biblepy +```bash +PYTHONUNBUFFERED=1 # Immediate log output +PYTHONDONTWRITEBYTECODE=1 # Skip .pyc files +PRELOAD_INTERLINEAR=true # Load interlinear data on startup +``` -## License +## Project Structure -<<<<<<< HEAD -### Typography and Reading Experience -- **Serif fonts** for Scripture text to enhance readability -- **Optimal line spacing** and margins for extended reading -- **Responsive text sizing** that adapts to screen size and user preferences -- **High contrast** for accessibility and eye comfort +``` +kjvstudy.org/ +├── kjvstudy_org/ +│ ├── server.py # Main FastAPI application +│ ├── kjv.py # Bible text access +│ ├── cross_references.py # Cross-reference data +│ ├── topics.py # Topical index +│ ├── interlinear_loader.py # Greek/Hebrew data +│ ├── reading_plans.py # Bible reading plans +│ ├── templates/ # Jinja2 templates +│ │ ├── base.html # Base template with Tufte CSS +│ │ ├── verse.html # Individual verse pages +│ │ ├── study_guides.html # Study guide templates +│ │ └── ... +│ └── static/ # Static assets +├── Dockerfile # Container configuration +├── fly.toml # Fly.io deployment config +├── pyproject.toml # Python dependencies +└── README.md # This file +``` -### User Interface -- **Minimalist design** that keeps focus on the text -- **Intuitive navigation** that doesn't distract from study -- **Progressive disclosure** of features to avoid overwhelming new users -- **Consistent visual hierarchy** throughout the application +## Contributing -### Performance -- **Fast loading times** for immediate access to Scripture -- **Efficient caching** of frequently accessed content -- **Progressive enhancement** for users with slower connections -- **Offline capability** for core reading features (planned) +We welcome contributions! Areas where you can help: -## 🔮 Future Enhancements +**Development:** +- Backend optimization and new features +- Frontend improvements and accessibility +- Mobile app development +- API development for external integrations -### Content Expansion -- Multiple Bible translations and versions -- Original language tools (Hebrew, Greek) -- Historical Bible versions and manuscripts -- Integration with Bible atlases and timelines +**Content:** +- Theological review for accuracy +- Additional study guides and resources +- Original language expertise (Greek/Hebrew) +- Historical and cultural context -### Study Tools -- Note-taking and highlighting system -- Bible reading plans and tracking +**Design:** +- UI/UX improvements +- Accessibility enhancements +- Mobile experience optimization +- Print stylesheet development + +**Documentation:** +- Tutorials and how-to guides +- API documentation +- User guides +- Translation to other languages + +## Roadmap + +**Planned Features:** +- Multiple Bible translations (ESV, NASB, NIV) +- User accounts with note-taking and highlighting +- Bible reading plans with progress tracking +- AI-powered commentary generation +- Mobile applications (iOS/Android) - Prayer journal integration - Scripture memorization tools +- Community discussion forums +- Live streaming integration for Bible studies -### AI-Powered Features -- Automatic sermon generation from passages -- Bible study curriculum creation -- Personalized devotional content -- Intelligent study group matching - -### Community Features -- User profiles and study progress tracking -- Discussion forums for passage exploration -- Expert commentary from biblical scholars -- Live streaming of Bible studies and sermons - -## 🤝 Contributing - -We welcome contributions from developers, theologians, and Bible enthusiasts! Here's how you can help: - -### For Developers -- Frontend improvements and responsive design -- Backend optimization and new features -- AI integration and commentary generation -- Testing and quality assurance - -### For Biblical Scholars -- Content review and theological accuracy -- Historical and cultural context insights -- Cross-reference suggestions and verification -- Study question and outline creation - -### For Users -- Bug reports and feature requests -- User experience feedback -- Beta testing of new features -- Community building and engagement - -## 📄 License +## License This project is open source and available under the [ISC License](LICENSE). -## 🙏 Acknowledgments +## Acknowledgments -- **King James Bible (1769)**: The foundational text that makes this project possible -- **FastAPI Community**: For the excellent web framework -- **Open Source Community**: For the tools and libraries that power this application -- **Biblical Scholars**: Whose centuries of study inform our AI commentary approach - -## 📞 Contact - -For questions, suggestions, or collaboration opportunities: -- Create an issue on GitHub -- Join our community discussions -- Follow development updates +- **King James Bible (1769)** - The foundational text +- **FastAPI Community** - Excellent web framework +- **Edward Tufte** - Design philosophy and CSS inspiration +- **Open Source Community** - Tools and libraries that make this possible --- -*"Study to shew thyself approved unto God, a workman that needeth not to be ashamed, rightly dividing the word of truth."* - 2 Timothy 2:15 (KJV) -======= -See LICENSE file for details. ->>>>>>> bb2748c (Simplify README documentation) ->>>>>>> 56527a8 +*"Study to shew thyself approved unto God, a workman that needeth not to be ashamed, rightly dividing the word of truth."* +— 2 Timothy 2:15 (KJV)