patrick
d78b21c27f
Incoming files are matched against what is already stored, keyed on the KOReader hash and the file size. Bulk uploads skip and report them, deliberate creates are refused with a 409, the consume directory parks them aside, and allow_duplicates overrides all three. Also: books whose metadata generates a path another book already owns are moved aside, so a forced copy cannot overwrite the original's files.
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