docs: reorganize documentation structure for users and self-hosters

- Remove internal development docs (phase tracking, implementation plans, security audits) - Move DEVELOPMENT.md to docs/contributing/ for contributor guidance - Move TROUBLESHOOTING.md from root to docs/ folder - Add docs/INDEX.md as navigation hub for all documentation - Clean up docs to focus on user/self-hoster facing content This reorganization separates user-facing documentation from internal contributor documentation, making the project more approachable for self-hosters.
2026-02-01 17:33:40 -05:00
parent 6592db2c65
commit 7135571de8
14 changed files with 733 additions and 5459 deletions
@@ -0,0 +1,229 @@
+# 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