bookhoard/docs/INDEX.md

Bookhoard Documentation Index

Complete guide to Bookhoard documentation. Find what you need quickly.

---

🚀 Quick Links

For New Users

1. README.md - Start here! Project overview and quick start
2. docs/SYNC_USER_GUIDE.md - Understanding and using sync
3. docs/devices/KOBO_SETUP.md - Kobo e-reader setup
4. docs/devices/KOREADER_SETUP.md - KOReader setup

For Self-Hosting

1. docs/TROUBLESHOOTING.md - Deployment and troubleshooting
2. .env.example - Secrets configuration (JWT and DB password)

For Contributors

1. docs/contributing/DEVELOPMENT.md - Development workflow and architecture
2. docs/API_REFERENCE.md - Complete API documentation
3. docs/COLLECTIONS_API.md - Collections API
4. docs/api/WEBSOCKET_API.md - WebSocket protocol

---

📚 Documentation by Topic

Getting Started

• README.md - Project overview, features, quick start guide
• docs/contributing/DEVELOPMENT.md - Development environment setup

Deployment & Operations

• docs/TROUBLESHOOTING.md - Common deployment issues and solutions
• .env.example - Required secrets (JWT_SECRET, DBPASS)
• docker-compose.yml - Operational configuration with defaults
• Makefile - Build and test commands

Using Sync Features

• docs/SYNC_USER_GUIDE.md - Universal sync user guide
  • Understanding sync
  • Book matching and auto-linking
  • Conflict resolution
  • Best practices

Device Setup

• docs/devices/KOBO_SETUP.md - Kobo e-reader configuration

  • Device registration
  • Sync configuration
  • OPDS wireless book delivery
  • Troubleshooting

• docs/devices/KOREADER_SETUP.md - KOReader configuration

  • Installation on Kindle/Kobo/PocketBook
  • Sync setup
  • OPDS catalog access
  • Troubleshooting

API Documentation

• docs/API_REFERENCE.md - Complete REST API reference

  • Authentication
  • User management
  • Libraries
  • Media items
  • Reading progress
  • Notes & highlights
  • Analytics
  • Book matching
  • OPDS
  • Sync protocols (KOReader, Kobo)
  • WebSocket

• docs/COLLECTIONS_API.md - Collections API

  • Create and manage collections
  • Auto-assign rules
  • Test rules
  • Bulk operations
  • Device shelf mappings

• docs/api/WEBSOCKET_API.md - WebSocket protocol

  • Connection flow
  • Message format
  • Real-time sync broadcasts
  • Authentication

Contributing

• docs/contributing/DEVELOPMENT.md - Development guide

  • Architecture overview
  • Directory structure
  • Local development setup
  • Testing guidelines
  • Code style
  • Deployment

• PROJECT_GUIDELINES.md - Development rules and standards

  • Critical prohibitions
  • Mandatory requirements
  • Error recovery protocol

Reference

• go.mod - Go dependencies
• database/schema/schema.sql - Database schema
• bruno/ - API test collections

---

📖 Reading Path by Role

Self-Hoster / End User

Goal: Set up and use Bookhoard for reading

1. Start with README.md - Understand what Bookhoard is
2. Follow quick start in README.md to get running
3. Set up your device:
   • Kobo: docs/devices/KOBO_SETUP.md
   • KOReader: docs/devices/KOREADER_SETUP.md
4. Learn about sync: docs/SYNC_USER_GUIDE.md
5. If issues arise: docs/TROUBLESHOOTING.md

Developer

Goal: Contribute to Bookhoard or integrate with it

1. Start with README.md - Project overview
2. Read docs/contributing/DEVELOPMENT.md - Architecture and setup
3. Review docs/API_REFERENCE.md - API endpoints
4. Check PROJECT_GUIDELINES.md - Development rules
5. Explore codebase and contribute!

API Integrator

Goal: Build integration with Bookhoard

1. Review README.md - Feature overview
2. Study docs/API_REFERENCE.md - All endpoints
3. Check specialized docs:
   • Collections: docs/COLLECTIONS_API.md
   • WebSocket: docs/api/WEBSOCKET_API.md
   • Sync: docs/SYNC_USER_GUIDE.md
4. Test with bruno/ collections

---

🔍 Quick Find

"How do I..."

...do this?	See this document
...install Bookhoard?	README.md - Quick Start
...set up my Kobo?	docs/devices/KOBO_SETUP.md
...set up KOReader?	docs/devices/KOREADER_SETUP.md
...understand sync?	docs/SYNC_USER_GUIDE.md
...resolve conflicts?	docs/SYNC_USER_GUIDE.md - Managing Conflicts
...match books?	docs/SYNC_USER_GUIDE.md - Book Matching
...troubleshoot deployment?	docs/TROUBLESHOOTING.md
...use the API?	docs/API_REFERENCE.md
...set up development?	docs/contributing/DEVELOPMENT.md
...contribute code?	docs/contributing/DEVELOPMENT.md - Contributing

"Where is..."

...this information?	See this document
...features list?	README.md
...database schema?	database/schema/schema.sql
...API endpoints?	docs/API_REFERENCE.md
...secrets config?	.env.example
...operational config?	docker-compose.yml
...deployment issues?	docs/TROUBLESHOOTING.md

---

📊 Documentation Statistics

File	Lines	Purpose	Audience
README.md	150	Overview & quick start	Everyone
contributing/DEVELOPMENT.md	450	Development workflow	Contributors
API_REFERENCE.md	1,300+	Complete REST API	Developers, integrators
COLLECTIONS_API.md	494	Collections API	Developers, integrators
SYNC_USER_GUIDE.md	350+	Sync usage guide	End users
TROUBLESHOOTING.md	300	Deployment troubleshooting	Self-hosters
KOBO_SETUP.md	598	Kobo setup	Kobo users
KOREADER_SETUP.md	504	KOReader setup	KOReader users
WEBSOCKET_API.md	676	WebSocket protocol	Developers
PROJECT_GUIDELINES.md	250	Development rules	Developers

Total: ~5,000 lines of comprehensive documentation

---

🎯 Common Tasks

Set up a new device

1. Device setup guide: docs/devices/KOBO_SETUP.md or docs/devices/KOREADER_SETUP.md
2. Sync overview: docs/SYNC_USER_GUIDE.md
3. Troubleshooting: Device-specific setup guides

Troubleshoot sync issues

1. Check docs/SYNC_USER_GUIDE.md - "Managing Conflicts" and "Best Practices"
2. Review device-specific guide for common issues
3. Check docs/TROUBLESHOOTING.md for general issues

Integrate with Bookhoard API

1. Start with docs/API_REFERENCE.md - Complete API reference
2. Check docs/COLLECTIONS_API.md for collections
3. Review docs/api/WEBSOCKET_API.md for real-time updates
4. Use bruno/ test collections as examples

Deploy to production

1. Follow README.md quick start
2. Configure environment: .env.example
3. Review docs/TROUBLESHOOTING.md for common issues
4. Check docs/contributing/DEVELOPMENT.md for performance tuning

---

📝 Contributing to Documentation

When adding new features:

1. Update README.md - Add to features list if user-facing
2. Update docs/API_REFERENCE.md - Document new endpoints
3. Add/update tests in bruno/
4. Update relevant guides (SYNC_USER_GUIDE.md, device guides, etc.)
5. Keep PROJECT_GUIDELINES.md in mind

---

Last Updated: 2026-02-01
Bookhoard Version: 1.0