hxbooks/docs/development-plan.md

HXBooks Development Plan & Progress

User's Priorities (March 2026)

1. ✅ Fix the domain and data model
2. ✅ Make sure everything related to the database is good
3. 🚧 Make a CLI so I can test things manually (In Progress)
4. Make sure search and other basic functionality is good and can be accessed through CLI
5. Set up automated tests
6. Fully rework the GUI

Everything else will come later.

---

✅ COMPLETED: Domain Model & Database (Phase 1-2)

Domain Model Decisions Made

• No book/instance separation: Keep it simple, treat duplicate editions as separate books
• Author/Genre relationships: Proper many-to-many instead of JSON fields
• Location hierarchy: location_place + location_bookshelf + location_shelf (numeric)
• Auto-complete approach: Authors/genres created on-demand with nice UI later
• Multiple readings: Separate records per reading session
• Simple loaning: loaned_to string + loaned_date for tracking

Database Infrastructure ✅ DONE

• ✅ Flask-Migrate + Alembic set up
• ✅ Initial migration created and applied
• ✅ Fixed instance folder location (project root instead of src/instance)
• ✅ Database in correct location: /hxbooks.sqlite
• ✅ All tables created: author, genre, book, book_author, book_genre, reading, wishlist

New Data Model ✅ IMPLEMENTED

-- Core entities
Author(id, name)
Genre(id, name)  
Book(id, title, description, isbn, edition, publisher, notes, 
     added_date, bought_date,
     location_place, location_bookshelf, location_shelf,
     loaned_to, loaned_date, owner_id)

-- Many-to-many relationships  
BookAuthor(book_id, author_id)
BookGenre(book_id, genre_id)

-- User activity
Reading(id, user_id, book_id, start_date, end_date, 
        finished, dropped, rating, comments)
Wishlist(id, user_id, book_id, wishlisted_date)

---

🚧 IN PROGRESS: CLI Development (Phase 3)

CLI Requirements for Manual Testing

• Book CRUD operations (add, edit, delete, list)
• Author/Genre management (auto-create, list)
• Location management (place, bookshelf, shelf)
• Reading tracking (start, finish, rate)
• Search functionality testing
• Data import from old format
• Loaning operations

CLI Commands Planned

hx book add "Title" --authors "Author1,Author2" --genres "Fiction"
hx book list --location "my house" --shelf 2
hx book search "keyword"
hx reading start <book_id>
hx reading finish <book_id> --rating 4
hx loan <book_id> --to "Alice" 

---

📋 TODO: Remaining Phases

Phase 4: Search & Core Features

• Implement proper FTS with new schema
• Add faceted search (by author, genre, location)
• Create search result serializers
• Add pagination
• Optimize query performance with proper indexes

Phase 5: Testing Framework

• Set up pytest with database fixtures
• API endpoint tests
• Search functionality tests
• CLI command tests
• Migration tests

Phase 6: GUI Rework

• Update templates for new data model
• Mobile-first responsive design
• Author/Genre autocomplete interfaces
• Location hierarchy picker
• Touch-optimized interactions

---

🗄️ Original Critique Archive

Critical Issues RESOLVED ✅

• ❌ Book ownership model: Fixed - no artificial scarcity
• ❌ JSON denormalization: Fixed - proper Author/Genre relationships
• ❌ Mixed properties: Fixed - structured location hierarchy
• ❌ No migrations: Fixed - Alembic set up and working
• ❌ Poor folder structure: Fixed - database in project root

Issues for Later Phases

• Authentication: Username-only insufficient (Phase 6+)
• Configuration management: No environment handling (Phase 6+)
• Mobile UX: Tables don't work on mobile (Phase 6)
• Testing infrastructure: No framework yet (Phase 5)
• Error handling: No proper boundaries (Phase 6+)
• Performance: No indexing strategy yet (Phase 4)

---

Last updated: March 14, 2026 Status: Phase 1-2 Complete ✅ | Phase 3 In Progress 🚧

Medium Priority Issues (Priority 3-4: CLI & Search)

Search & Discovery

• Limited FTS capabilities: Current implementation incomplete
• No faceted search: Missing filters by author, genre, year, etc.
• Performance concerns: JSON contains operations will be slow
• Missing recommendations: No "similar books" functionality

CLI Requirements for Testing

• Book CRUD operations
• Search functionality testing
• User management
• Reading tracking
• Data import/export capabilities

Lower Priority Issues (Priority 5-6: Testing & GUI)

Testing Infrastructure Missing

• No testing framework configured
• No test database setup
• No fixtures or mock data
• No CI/CD pipeline

GUI/UX Issues

• Mobile responsiveness needs work
• No offline capabilities
• Tables don't work well on mobile
• Missing accessibility features

Security & DevOps (Future)

• Authentication: Username-only is insufficient
• Configuration management: No environment handling
• Deployment: Dockerfile/requirements.txt mismatch
• Secret management: Hardcoded dev secrets

Technical Debt

• Python 3.14 requirement: Too aggressive (doesn't exist yet)
• Error handling: No proper error boundaries
• Logging: No production logging configuration
• Code quality: Missing linting, formatting tools

---

Implementation Notes

Phase 1: Domain Model Rework

• Design new schema with proper relationships
• Create migration system
• Implement Author and Genre entities
• Separate Book from BookInstance
• Update all models with proper typing

Phase 2: Database Infrastructure

• Set up Alembic migrations
• Add proper indexing
• Implement FTS correctly
• Add database constraints
• Create seed data

Phase 3: CLI Development

• Create Click-based CLI
• Book management commands
• Search functionality
• User operations
• Import/export tools

Phase 4: Search & Core Features

• Implement proper FTS
• Add faceted search
• Create search result serializers
• Add pagination
• Optimize query performance

Phase 5: Testing Framework

• Set up pytest
• Database testing fixtures
• API endpoint tests
• Search functionality tests
• CLI command tests

Phase 6: GUI Rework

• Mobile-first responsive design
• Progressive enhancement
• Accessibility improvements
• Modern HTMX patterns
• Touch-optimized interactions

---

Last updated: March 14, 2026