patrick
22539644a9
Files move on disk before any row moves, then everything repoints in one transaction and the folded records are deleted. Progress keeps whichever is furthest, shelves and tags union, and identifiers move only under a name the survivor lacks. Metadata is left alone unless the caller resolves it, since choosing between two titles is a judgement this endpoint cannot make. Nothing is removed from disk.
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