# Chitai API

A RESTful API for managing ebooks, built with [Litestar](https://litestar.dev/) 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):
```bash
uv sync
```

### 2. Environment Configuration

Copy the example environment file and configure environment variables:
```bash
cp .env.example .env
```

### 3. Database Setup

Run migrations:
```bash
alchemy --config chitai.database.config.config upgrade
```

### 4. Run the Application

Development mode with auto-reload:
```bash
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:
```bash
pytest tests/
```

Run specific test categories:
```bash
# Unit tests only
pytest tests/unit

# Integration tests only
pytest tests/integration
```

### Code Quality

Format code:
```bash
ruff format src/
```

### Creating Database Migrations

After modifying models:
```bash
alchemy --config chitai.database.config.config make-migrations
```

For manual migrations:
```bash
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