hxbooks/.github/copilot-instructions.md

HXBooks Project Guidelines

Project Overview

HXBooks is a personal book library management application with both web (Flask + HTMX) and CLI interfaces. It provides advanced book searching, reading tracking, and library management without heavy JavaScript frameworks.

Core Technologies:

• Backend: Flask 3.1+ with SQLAlchemy 2.0 (modern Mapped[] annotations)
• Frontend: HTMX + Alpine.js + Bootstrap (minimal JavaScript approach)
• Validation: Pydantic 2.x with modern Annotated types for composable validation
• Templates: Jinja2 with fragments for partial page updates
• Database: SQLite with proper normalized schema (no JSON columns for core entities)
• Package Manager: UV with Python 3.14
• CLI: Click-based comprehensive command interface

Architecture

Service Layer Pattern:

• Flask app factory in src/hxbooks/app.py
• Service layer: src/hxbooks/library.py - business logic shared between web and CLI
• Web routes: src/hxbooks/main.py - Flask blueprint handling HTTP requests
• CLI commands: src/hxbooks/cli.py - Click command groups

Key Components:

• src/hxbooks/models.py: SQLAlchemy models with proper normalization and relationships
• src/hxbooks/library.py: Core business logic (create_book, search_books_advanced, etc.)
• src/hxbooks/search.py: Advanced query parser with pyparsing
• src/hxbooks/gbooks.py: Google Books API integration
• src/hxbooks/templates/: Jinja2 templates with HTMX fragments

Build and Development

Setup & Run:

uv sync                    # Install dependencies
python -m hxbooks          # Dev server with livereload (port 5000)
hxbooks --help             # CLI interface (after uv sync)

CLI Commands:

hxbooks book add "Title" --authors "Author1,Author2" --genres "Fiction" 
hxbooks book search "author:tolkien genre:fantasy rating>=4"
hxbooks reading start <book_id>
hxbooks reading finish <book_id> --rating 5 --comments "Excellent!"
hxbooks wishlist add <book_id>

Development Server:

• CLI command hxbooks serve: Livereload server watching templates
• VS Code debugging: Flask app factory in src/hxbooks/app.py
• Config: Instance folder pattern (instance/config.py for local overrides)

Testing:

pytest                     # Run all tests with verbose output
pytest tests/test_cli.py   # Test CLI commands
pytest tests/test_search.py # Test query parser

Production Deployment:

• Dockerfile uses Gunicorn on port 8080
• Note: Current Dockerfile expects requirements.txt but project uses pyproject.toml

Code Style

Python Conventions:

• Types: Modern annotations (str | Response, Mapped[str], Optional[Type])
• Naming: snake_case functions/vars, PascalCase classes, UPPERCASE constants
• SQLAlchemy: Use mapped_column() and relationship() with back_populates
• Validation: Pydantic schemas with {Entity}FormData pattern

Pydantic 2.x Patterns:

• Composable types: Annotated[str, StringConstraints(strip_whitespace=True)]
• Custom validators: BeforeValidator() for preprocessing (strip, empty-to-None)
• Reusable aliases: StrOrNone, TextareaList, ISBNOrNone in src/hxbooks/main.py
• Modern syntax: str | None not Optional[str], model_validate() not parse_obj()

Flask Patterns:

• Blueprints with @bp.route() decorators
• @login_required decorator for protected routes
• Response types: str | Response (template string or redirect)
• Error handling: Dict mapping for template display {field: error_msg}

Testing Conventions:

• pytest: Class-based organization (TestBookAddCommand, TestFieldFilters)
• Parametrized tests: @pytest.mark.parametrize for multiple scenario testing
• Type hints: Full annotations on test methods and fixtures
• Assertions: Include context with f-strings for debugging

Frontend (HTMX + Alpine.js):

• Templates: .j2 extension, fragments for partial updates
• HTMX: Dynamic updates with hx-get, hx-post, hx-target
• Alpine.js: Minimal state management (x-data, x-show, @click)
• Styling: Bootstrap CSS classes

Key Files

Entry Points:

• src/hxbooks/main.py: Development server
• main.py: Unused placeholder
• .vscode/launch.json: Debug configuration

Core Application:

• src/hxbooks/app.py: Flask app factory
• src/hxbooks/db.py: SQLAlchemy setup with auto-table creation
• src/hxbooks/models.py: Database models

Feature Modules:

• src/hxbooks/main.py: Web routes and form handling
• src/hxbooks/library.py: Business logic service layer
• src/hxbooks/cli.py: Click CLI commands
• src/hxbooks/search.py: Query parser and search logic
• src/hxbooks/gbooks.py: Google Books API integration

Testing Infrastructure:

• tests/conftest.py: Pytest fixtures and test configuration
• tests/test_cli.py: CLI command tests
• tests/test_search.py: Query parser and search tests

Conventions

Database Patterns:

• Normalized schema: Author and Genre as separate entities with many-to-many relationships
• Cascade deletes for dependent entities
• Foreign key constraints explicitly defined

Search Implementation:

• Advanced query parser using pyparsing with field filters (author:tolkien, rating>=4)
• Complex query builder returning Select statements
• Support for negation (-genre:romance) and special operators (is:reading)

HTMX Integration:

• Partial page updates using Jinja2-Fragments
• Search results rendered as blocks without full page reload
• Form validation errors returned as template fragments

Development Notes:

• Testing framework: pytest with parametrized tests for comprehensive coverage
• Linting/formatting: ruff configured with strict rules
• Instance folder for environment-specific config (gitignored)
• Production requires either requirements.txt generation or Dockerfile updates for UV