103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
# 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 |