hxbooks/.github/copilot-instructions.md

HXBooks Project Guidelines

Project Overview

HXBooks is a personal book library management application built with Flask, HTMX, and SQLAlchemy. It provides dynamic 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 schemas for request/response validation
• Templates: Jinja2 with fragments for partial page updates
• Database: SQLite with JSON columns for flexible arrays
• Package Manager: UV with Python 3.14

Architecture

Application Factory Pattern:

• create_app() in src/hxbooks/init.py
• Blueprint organization: auth.py (authentication), book.py (main features)
• Models: User, Book, Reading, Wishlist with cascade relationships

Key Components:

• src/hxbooks/models.py: SQLAlchemy models with modern Mapped[] syntax
• src/hxbooks/book.py: Complex search with Pydantic validation
• 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)

Development Server:

• src/hxbooks/main.py: Livereload server watching templates
• VS Code debugging: Use "Python Debugger: Flask" launch configuration
• Config: Instance folder pattern (instance/config.py for local overrides)

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}RequestSchema/{Entity}ResultSchema pattern

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}

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/init.py: Flask app factory
• src/hxbooks/db.py: SQLAlchemy setup with auto-table creation
• src/hxbooks/models.py: Database models

Feature Modules:

• src/hxbooks/auth.py: User authentication (username-based)
• src/hxbooks/book.py: Book CRUD, search, filtering
• src/hxbooks/gbooks.py: Google Books API integration

Conventions

Database Patterns:

• JSON columns for arrays: authors: list, genres: list, saved_searches: dict
• Cascade deletes for dependent entities
• Foreign key constraints explicitly defined

Search Implementation:

• Full-text search using SQLite FTS with func.match()
• Complex query builder returning Select statements
• Saved searches stored as JSON in User model

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:

• No testing framework configured yet
• No linting/formatting tools setup
• Instance folder for environment-specific config (gitignored)
• Production requires either requirements.txt generation or Dockerfile updates for UV