# Bookhoard Documentation Index

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

---

## 🚀 Quick Links

### For New Users
1. [README.md](../README.md) - **Start here!** Project overview and quick start
2. [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Understanding and using sync
3. [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) - Kobo e-reader setup
4. [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md) - KOReader setup

### For Self-Hosting
1. [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Deployment and troubleshooting
2. [.env.example](../.env.example) - Secrets configuration (JWT and DB password)

### For Contributors
1. [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Development workflow and architecture
2. [docs/API_REFERENCE.md](API_REFERENCE.md) - Complete API documentation
3. [docs/COLLECTIONS_API.md](COLLECTIONS_API.md) - Collections API
4. [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md) - WebSocket protocol

---

## 📚 Documentation by Topic

### Getting Started
- **[README.md](../README.md)** - Project overview, features, quick start guide
- **[docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md)** - Development environment setup

### Deployment & Operations
- **[docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common deployment issues and solutions
- **[.env.example](../.env.example)** - Required secrets (JWT_SECRET, DBPASS)
- **[docker-compose.yml](../docker-compose.yml)** - Operational configuration with defaults
- **[Makefile](../Makefile)** - Build and test commands

### Using Sync Features
- **[docs/SYNC_USER_GUIDE.md](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](devices/KOBO_SETUP.md)** - Kobo e-reader configuration
  - Device registration
  - Sync configuration
  - OPDS wireless book delivery
  - Troubleshooting

- **[docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)** - KOReader configuration
  - Installation on Kindle/Kobo/PocketBook
  - Sync setup
  - OPDS catalog access
  - Troubleshooting

### API Documentation
- **[docs/API_REFERENCE.md](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.md)** - Collections API
  - Create and manage collections
  - Auto-assign rules
  - Test rules
  - Bulk operations
  - Device shelf mappings

- **[docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md)** - WebSocket protocol
  - Connection flow
  - Message format
  - Real-time sync broadcasts
  - Authentication

### Contributing
- **[docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md)** - Development guide
  - Architecture overview
  - Directory structure
  - Local development setup
  - Testing guidelines
  - Code style
  - Deployment

- **[PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md)** - Development rules and standards
  - Critical prohibitions
  - Mandatory requirements
  - Error recovery protocol

### Reference
- **[go.mod](../go.mod)** - Go dependencies
- **[database/schema/schema.sql](../database/schema/schema.sql)** - Database schema
- **[bruno/](../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](../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](devices/KOBO_SETUP.md)
   - KOReader: [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)
4. Learn about sync: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
5. If issues arise: [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)



### Developer
**Goal**: Contribute to Bookhoard or integrate with it

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

### API Integrator
**Goal**: Build integration with Bookhoard

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

---

## 🔍 Quick Find

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

### "Where is..."
| ...this information? | See this document |
|-------------------|------------------|
| ...features list? | [README.md](../README.md) |
| ...database schema? | [database/schema/schema.sql](../database/schema/schema.sql) |
| ...API endpoints? | [docs/API_REFERENCE.md](API_REFERENCE.md) |
| ...secrets config? | [.env.example](../.env.example) |
| ...operational config? | [docker-compose.yml](../docker-compose.yml) |
| ...deployment issues? | [docs/TROUBLESHOOTING.md](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](devices/KOBO_SETUP.md) or [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)
2. Sync overview: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
3. Troubleshooting: Device-specific setup guides

### Troubleshoot sync issues
1. Check [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - "Managing Conflicts" and "Best Practices"
2. Review device-specific guide for common issues
3. Check [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) for general issues

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

### Deploy to production
1. Follow [README.md](../README.md) quick start
2. Configure environment: [.env.example](../.env.example)
3. Review [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
4. Check [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) for performance tuning

---

## 📝 Contributing to Documentation

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

---

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