patrick
bd8d68b9ba
file.path is relative to book.path, so the archive matched nothing on disk and came out empty. Also namespace entries per book to stop filename collisions, and stream the zip instead of buffering it whole.
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