Skip to content

README.md

Latest commit

 

History

History
116 lines (82 loc) · 4.59 KB

README.md

File metadata and controls

116 lines (82 loc) · 4.59 KB

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.