chitai/backend/README.md

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