# 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**
4. ✅ **Make sure search and other basic functionality is good and can be accessed through CLI**
5. ✅ **Set up automated tests**
6. ✅ **Make sure search and other basic functionality is good**
7. **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
```sql
-- 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)
```

---

## ✅ COMPLETED: CLI Development (Phase 3)

### CLI Implementation ✅ DONE
- ✅ **Business logic separation**: Clean `services.py` module independent from web concerns
- ✅ **Book CRUD operations**: Create, read, update, delete books with proper validation
- ✅ **Author/Genre management**: Auto-create on-demand with many-to-many relationships
- ✅ **Location management**: Place, bookshelf, shelf hierarchy with filtering
- ✅ **Reading tracking**: Start, finish, drop, rate reading sessions
- ✅ **Wishlist operations**: Add, remove, list wishlist items
- ✅ **Advanced search**: pyparsing-based query language with field filters and comparison operators
- ✅ **ISBN import**: Google Books API integration for book metadata
- ✅ **Database utilities**: Status, initialization, seed data commands
- ✅ **Output formats**: Human-readable tables and JSON for scripting

### Advanced Search Language ✅ IMPLEMENTED
```bash
# Working CLI commands:
hxbooks book add "Title" --owner alice --authors "Author1,Author2" --genres "Fiction"
hxbooks book list --place "home" --bookshelf "office" --shelf 2
hxbooks book search "author:tolkien genre:fantasy"
hxbooks book search "shelf>=5 title:\"Lord of Rings\""
hxbooks book search -- "-genre:romance"  # Negation
hxbooks reading start <book_id> --owner alice
hxbooks reading finish <book_id> --rating 4 --comments "Great book!"
hxbooks wishlist add <book_id> --owner alice
hxbooks book import 9780441172719 --owner alice  # ISBN import
```

### Search Query Language Features
- **Field-specific searches**: `author:tolkien`, `genre:"science fiction"`
- **Comparison operators**: `shelf>=5`, `added>=2025-01-01`, `rating>3`
- **Quoted strings**: `title:"The Lord of the Rings"`
- **Negation**: `-genre:romance`
- **Date comparisons**: `added>=2026-03-01`, `bought<2025-12-31`
- **Multiple filters**: `author:herbert genre:scifi owner:alice`

---

## ✅ COMPLETED: Automated Testing (Phase 4)

### Testing Framework ✅ IMPLEMENTED
- ✅ **pytest infrastructure**: Database fixtures, isolated test environments
- ✅ **CLI command tests**: All 18 commands with happy paths and error scenarios (29+ tests)
- ✅ **Advanced search tests**: Parametrized tests for field filters and complex queries
- ✅ **Query parser unit tests**: Type conversion, operator logic, edge cases (36 tests)
- ✅ **Output format validation**: JSON and table formats for all commands
- ✅ **Database integration**: Full CLI → services → database → relationships flow testing
- ✅ **Error handling tests**: Invalid inputs, missing data, constraint violations

### Test Coverage Achieved
- **CLI Integration**: Book CRUD, reading tracking, wishlist operations, database utilities
- **Search functionality**: String filters, numeric filters, date filters, negation, complex queries
- **Parser robustness**: Edge cases, type conversion, fallback behavior, unicode support
- **Database validation**: Relationship integrity, user creation, data persistence

**Decision**: Migration tests deemed unnecessary for this simple personal app
**Status**: 65+ tests passing, comprehensive coverage for critical functionality

---

## ✅ COMPLETED: Search & Core Features Enhancement (Phase 5)

### Search Improvements ✅ IMPLEMENTED
- ✅ **Enhanced search functionality**: Additional improvements implemented
- ✅ **Query optimization**: Performance and usability enhancements
- ✅ **Core feature refinements**: Various search and functionality improvements

**Status**: Search functionality enhanced and ready for production use

---

## 📋 TODO: Remaining Phases

### 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 (Future phases)
- **Configuration management**: No environment handling (Future phases) 
- **Mobile UX**: Tables don't work on mobile (Phase 6)
- **Error handling**: No proper boundaries (Future phases)
- **Performance**: No indexing strategy yet (Phase 4)

---

*Last updated: March 17, 2026*
*Status: Phases 1-5 Complete ✅ | Ready for Phase 6: GUI Rework 🎨*

### 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*