fran/hxbooks
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
hxbooks/docs/development-plan.md

8.9 KiB
Raw Permalink Blame History

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

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

# 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

Reference in New Issue View Git Blame Copy Permalink