patrick
8ee406533c
Extractors wrote whatever the file said, so one person held several rows: "Sam Newman" beside "Newman, Sam;" beside "Sam Newman.epub", the last because the upload path never stripped the file extension. Tidy on write, in the validator and in the uniqueness lookup alike, and merge the rows that collide.
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