127 lines
2.6 KiB
Markdown
127 lines
2.6 KiB
Markdown
# 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 |