Library

Full-stack library service with a Python backend and a Vue frontend.

The project contains a REST API for books, authors, categories, authentication, user reading progress, bookmarks, purchases, admin workflows, background parsing, and file storage. The frontend is a Vite/Vue application that consumes this API and provides the user interface for browsing and reading books.

Project Structure

.
|-- backend/            # API, database models, migrations, workers, parser, storage integrations
|-- frontend/           # Vue application, pages, components, stores, API client
|-- docker-compose.yml  # Root compose file that includes backend and frontend compose files

Main Parts

Backend

The backend lives in backend/.

It is responsible for:

• FastAPI application and API routes.
• PostgreSQL database models and Alembic migrations.
• Authentication, email verification, password reset, CSRF, and admin bootstrap.
• Redis cache integration.
• RabbitMQ and Taskiq background jobs.
• Automatic book parsing/import jobs from Gutendex.
• MinIO/S3-compatible storage for uploaded assets.

See backend/README.md for backend-specific structure and commands.

Frontend

The frontend lives in frontend/.

It is responsible for:

• Vue/Vite web application.
• Routing between auth, books, authors, categories, profile, reader, and admin pages.
• Pinia stores for auth, profile, and books.
• Axios API client with cookie auth, CSRF headers, and token refresh handling.
• Production build served by Nginx in Docker.

See frontend/README.md for frontend-specific structure and commands.

Common Places

• docker-compose.yml includes backend/docker-compose.yml and frontend/docker-compose.yml.
• backend/.env.example contains backend, database, Redis, RabbitMQ, MinIO, mail, security, CORS, parser, and admin settings.
• frontend/.env.example contains frontend host/port and Vite runtime settings.
• backend/alembic/versions/ contains database migrations.
• backend/app/api/v1/ contains backend route modules.
• backend/app/services/parser/ contains the Gutendex parser.
• backend/app/tasks/parser_tasks.py contains the scheduled parser task.
• frontend/src/pages/ contains route-level frontend views.
• frontend/src/shared/api/ contains frontend API clients and endpoint paths.

Automatic Gutendex Parser

The project includes an automatic parser that imports books from Gutendex, a public API for Project Gutenberg book metadata and text links.

How it works:

• The backend starts from PARSER_API_BASE, which defaults to https://gutendex.com.
• It discovers categories from popular Gutendex books by reading their subjects and bookshelves.
• For each category, it requests GET /books/?topic=<category>&sort=popular.
• For each matching book, it extracts the title, first author, author years, summary, cover URL, and plain-text book URL.
• It downloads the plain-text content, removes Project Gutenberg boilerplate, normalizes text, and splits the book into internal pages.
• It saves categories, authors, books, and book pages into PostgreSQL in batches.
• It skips duplicates by title, author, and category before downloading and before saving.

The parser can run automatically through the Taskiq scheduler and can also be queued once by the parser_bootstrap Docker service.

Parser behavior is controlled by backend environment variables such as category limits, books per author, page size, request retries, and batch size. See backend/README.md for details.

Quick Start With Docker

Create local environment files:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

Start the full project from the repository root:

docker compose up -d --build

Default local URLs from the example environment:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• Backend OpenAPI docs: http://localhost:8000/docs
• RabbitMQ UI: http://localhost:15672
• MinIO UI: http://localhost:9001

Useful compose commands:

docker compose ps
docker compose logs -f api
docker compose logs -f frontend
docker compose down

Development Notes

• Keep backend-specific changes documented in backend/README.md.
• Keep frontend-specific changes documented in frontend/README.md.
• If API prefixes or ports change, update both .env files so the frontend still points to the backend.
• The backend API prefix is built from API_PREFIX and API_V1_PREFIX.
• The frontend API base URL is built from VITE_API_URL, VITE_API_PREFIX, and VITE_API_VERSION.