Initial commit

backend/README.md

@@ -0,0 +1,127 @@
+# 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