766fca2c39
Updated book progress model in anticipation of the KOReader sync feature. Renamed properties: - renamed "progress" to "percentage" - renamed "pdf_loc" to "pdf_page" - renamed "epub_loc" to "epub_cfi" New properties: - "epub_xpointer", marks the location of an epub in KOReader - "device", the device type that updated the progress - "device_id", the id of the device that updated the progress
Chitai API
A RESTful API for managing ebooks, built with Litestar and Python.
Overview
This backend service provides a comprehensive API for ebook management, including:
- Ebook catalog management (CRUD operations)
- Virtual libraries and user bookshelves
- Metadata management (authors, publishers, tags, identifiers)
- File storage and retrieval
- Search and filtering capabilities
- Reading progress tracking
- User library management
Tech Stack:
- Python 3.13
- Litestar (ASGI web framework)
- Advanced-alchemy/SQLAlchemy (ORM)
- PostgreSQL (database)
- Alembic (migrations)
Prerequisites
- Python 3.13
- PostgreSQL 17
- uv
Getting Started
1. Install Dependencies
Using uv (recommended):
uv sync
2. Environment Configuration
Copy the example environment file and configure environment variables:
cp .env.example .env
3. Database Setup
Run migrations:
alchemy --config chitai.database.config.config upgrade
4. Run the Application
Development mode with auto-reload:
uv run litestar --app-dir src/chitai/ run --reload
The API will be available at http://localhost:8000
Development
Project Structure
backend/
├── src/
| └── chitai
| | ├── app.py # Litestar app initialization
| | ├── config.py # Configuration settings
| | ├── controllers # API route handlers
| | ├── database
| | │ ├── models # SQLAlchemy models
| | ├── exceptions # Custom exceptions and handlers
| | ├── schemas # Pydantic schemas (DTOs)
| | └── services # Business logic layer
├── migrations/ # Alembic migrations
├── tests/
│ ├── unit/
│ ├── integration/
│ └── conftest.py
├── alembic.ini
├── pyproject.toml
└── README.md
Running Tests
Run all tests:
pytest tests/
Run specific test categories:
# Unit tests only
pytest tests/unit
# Integration tests only
pytest tests/integration
Code Quality
Format code:
ruff format src/
Creating Database Migrations
After modifying models:
alchemy --config chitai.database.config.config make-migrations
For manual migrations:
alchemy --config chitai.database.config.config make-migrations --no-autogenerate
API Documentation
Once the server is running, interactive API documentation is available at:
- Swagger UI: http://localhost:8000/schema/
- OpenAPI JSON: http://localhost:8000/schema/openapi.json