142 lines
6.3 KiB
Markdown
142 lines
6.3 KiB
Markdown
# 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](src/hxbooks/app.py)
|
|
- Service layer: [src/hxbooks/library.py](src/hxbooks/library.py) - business logic shared between web and CLI
|
|
- Web routes: [src/hxbooks/main.py](src/hxbooks/main.py) - Flask blueprint handling HTTP requests
|
|
- CLI commands: [src/hxbooks/cli.py](src/hxbooks/cli.py) - Click command groups
|
|
|
|
**Key Components:**
|
|
- [src/hxbooks/models.py](src/hxbooks/models.py): SQLAlchemy models with proper normalization and relationships
|
|
- [src/hxbooks/library.py](src/hxbooks/library.py): Core business logic (create_book, search_books_advanced, etc.)
|
|
- [src/hxbooks/search.py](src/hxbooks/search.py): Advanced query parser with pyparsing
|
|
- [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)
|
|
hxbooks --help # CLI interface (after uv sync)
|
|
```
|
|
|
|
**CLI Commands:**
|
|
```bash
|
|
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](src/hxbooks/app.py)
|
|
- Config: Instance folder pattern (`instance/config.py` for local overrides)
|
|
|
|
**Testing:**
|
|
```bash
|
|
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](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](src/hxbooks/__main__.py): Development server
|
|
- [main.py](main.py): Unused placeholder
|
|
- [.vscode/launch.json](.vscode/launch.json): Debug configuration
|
|
|
|
**Core Application:**
|
|
- [src/hxbooks/app.py](src/hxbooks/app.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/main.py](src/hxbooks/main.py): Web routes and form handling
|
|
- [src/hxbooks/library.py](src/hxbooks/library.py): Business logic service layer
|
|
- [src/hxbooks/cli.py](src/hxbooks/cli.py): Click CLI commands
|
|
- [src/hxbooks/search.py](src/hxbooks/search.py): Query parser and search logic
|
|
- [src/hxbooks/gbooks.py](src/hxbooks/gbooks.py): Google Books API integration
|
|
|
|
**Testing Infrastructure:**
|
|
- [tests/conftest.py](tests/conftest.py): Pytest fixtures and test configuration
|
|
- [tests/test_cli.py](tests/test_cli.py): CLI command tests
|
|
- [tests/test_search.py](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 |