# 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](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](src/hxbooks/models.py): SQLAlchemy models with modern `Mapped[]` syntax
- [src/hxbooks/book.py](src/hxbooks/book.py): Complex search with Pydantic validation
- [src/hxbooks/gbooks.py](src/hxbooks/gbooks.py): Google Books API integration
- [src/hxbooks/templates/](src/hxbooks/templates/): Jinja2 templates with HTMX fragments

## Build and Development

**Setup & Run:**
```bash
uv sync                    # Install dependencies
python -m hxbooks          # Dev server with livereload (port 5000)
```

**Development Server:**
- [src/hxbooks/__main__.py](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](src/hxbooks/__main__.py): Development server
- [main.py](main.py): Unused placeholder
- [.vscode/launch.json](.vscode/launch.json): Debug configuration

**Core Application:**
- [src/hxbooks/__init__.py](src/hxbooks/__init__.py): Flask app factory
- [src/hxbooks/db.py](src/hxbooks/db.py): SQLAlchemy setup with auto-table creation
- [src/hxbooks/models.py](src/hxbooks/models.py): Database models

**Feature Modules:**
- [src/hxbooks/auth.py](src/hxbooks/auth.py): User authentication (username-based)
- [src/hxbooks/book.py](src/hxbooks/book.py): Book CRUD, search, filtering
- [src/hxbooks/gbooks.py](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