From f9442b7e7c82d5428afcc07ecce713542477eced Mon Sep 17 00:00:00 2001 From: Den Date: Sun, 21 Jul 2024 04:26:32 +0300 Subject: [PATCH] enhance README files --- API.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 81 ++++++++++++++++++++++++++++--- 2 files changed, 218 insertions(+), 6 deletions(-) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..99cce5f --- /dev/null +++ b/API.md @@ -0,0 +1,143 @@ +## API Documentation + +### Authentication + +All endpoints under `/api` require authentication using Firebase. Include the `Authorization` header in your request +with a valid Firebase ID token: + +`Authorization: Bearer ` + +### Book Endpoints + +| Method | Endpoint | Description | Query Params | Path Params | Data Structures | +|----------|----------------------------|-------------------------------------------------|----------------------------------------------------------|-----------------|-------------------------| +| `POST` | `/api/books/add` | Create a new book in the user's library. | None | None | `Book` | +| `POST` | `/api/books/add/advanced` | Add book from advanced search to user's library | `isbn` (string), `index` (number) | None | None | +| `GET` | `/api/books/` | Retrieve books for the authenticated user. | `page` (number, default 1), `limit` (number, default 10) | None | `PaginatedBookResponse` | +| `GET` | `/api/books/:id` | Retrieve a book by ID. | None | `id` (string) | `Book` | +| `GET` | `/api/books/isbn/:isbn` | Retrieve a book by ISBN. | None | `isbn` (string) | `Book` | +| `GET` | `/api/books/bookshelf/:id` | Retrieve books from a specific bookshelf. | `page` (number, default 1), `limit` (number, default 10) | `id` (string) | `PaginatedBookResponse` | +| `PUT` | `/api/books/:id` | Update a book. | None | `id` (string) | `BookUpdate` | +| `DELETE` | `/api/books/:id` | Delete a book. | None | `id` (string) | None | + +#### Data Structures + +**`Book`:** + +```typescript +interface Book { + id: string; + userId: string; + bookshelfId: string; + isbn: string; + title: string; + author: string; + publishing: string; + description: string; + coverImage: string; + shopName: string; + createdAt: Date; + updatedAt: Date; +} +``` + +**`BookUpdate`:** + +```typescript +interface BookUpdate { + isbn?: string; + bookshelfId?: string; + title?: string; + author?: string; + publishing?: string; + description?: string; + coverImage?: string; + shopName?: string; + updatedAt: Date; +} +``` + +**`PaginatedBookResponse`:** + +```typescript +interface PaginatedBookResponse { + books: Book[]; + total: number; + page: number; + limit: number; +} +``` + +### Bookshelf Endpoints + +| Method | Endpoint | Description | Query Params | Path Params | Data Structures | +|----------|------------------------|--------------------------------------------------|----------------------------------------------------------|---------------|------------------------------| +| `POST` | `/api/bookshelves/add` | Create a new bookshelf. | None | None | `Bookshelf` | +| `GET` | `/api/bookshelves/` | Retrieve bookshelves for the authenticated user. | `page` (number, default 1), `limit` (number, default 10) | None | `PaginatedBookshelfResponse` | +| `GET` | `/api/bookshelves/:id` | Retrieve a bookshelf by ID. | None | `id` (string) | `Bookshelf` | +| `PUT` | `/api/bookshelves/:id` | Update a bookshelf. | None | `id` (string) | `BookshelfUpdate` | +| `DELETE` | `/api/bookshelves/:id` | Delete a bookshelf. | None | `id` (string) | None | + +#### Data Structures + +**`Bookshelf`:** + +```typescript +interface Bookshelf { + id: string; + userId: string; + name: string; + createdAt: Date; + updatedAt: Date; +} +``` + +**`BookshelfUpdate`:** + +```typescript +interface BookshelfUpdate { + name?: string; + updatedAt: Date; +} +``` + +**`PaginatedBookshelfResponse`:** + +```typescript +interface PaginatedBookshelfResponse { + bookshelves: Bookshelf[]; + total: number; + page: number; + limit: number; +} +``` + +### Search Endpoints + +| Method | Endpoint | Description | Query Params | Path Params | Data Structures | +|--------|------------------------|-----------------------------------------------------------|-----------------|-------------|------------------| +| `GET` | `/api/search/simple` | Search for a book by ISBN in the local database. | `isbn` (string) | None | `SearchResponse` | +| `GET` | `/api/search/advanced` | Perform an advanced search for a book by ISBN using gRPC. | `isbn` (string) | None | `SearchResponse` | + +#### Data Structures + +**`SearchResponse`:** + +```typescript +enum SearchStatus { + PROCESSING = 0, + SUCCESS = 1, + FAILED = 2, +} + +interface SearchResponse { + status: SearchStatus; + books: Book[]; +} +``` + +### Health Check Endpoint + +| Method | Endpoint | Description | Query Params | Path Params | Data Structures | +|--------|---------------|-------------------------------------------------------|--------------|-------------|-----------------| +| `GET` | `/api/health` | Checks the health of the server and its dependencies. | None | None | None | diff --git a/README.md b/README.md index 1361bf8..5bce0e7 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,78 @@ -# librakeeper-server +# Librakeeper Server -```shell -protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative proto/search.proto +*― A Robust Backend System for a Personal Book Library* + +Librakeeper Server is a backend system designed for managing a personal book library. It provides a robust set of +features, including user authentication, book management, bookshelf organization, and advanced search capabilities. The +system is built using a microservices architecture with asynchronous processing, ensuring efficient and scalable +operations. + +## Key Features + +* **User Authentication:** Secure authentication using Firebase. +* **Book Management:** Add, view, update, and delete books with detailed information (ISBN, title, author, publishing, + description, cover image, and shop). +* **Bookshelf Organization:** Create and manage personalized bookshelves to categorize books. +* **Search Functionality:** Find books by ISBN using simple (local database) or advanced (gRPC-based) search. +* **Microservice Architecture:** Leverage gRPC for efficient communication between the server, searcher, and + searcher-agent microservices. +* **Asynchronous Processing:** Utilize RabbitMQ for asynchronous book searching and processing. +* **Persistent Storage:** Store book and bookshelf data in a MongoDB database. +* **Containerization:** Easy deployment and setup using Docker and Docker Compose. + +## API Documentation + +For detailed information about the Librakeeper Server API, including available endpoints, data structures, and +authentication requirements, please refer to the comprehensive [API documentation](API.md). + +## Architecture Overview + +The system follows a microservice architecture, with components communicating via gRPC and RabbitMQ. + +```mermaid +graph TB + Server[Librakeeper Server] -- gRPC --> Searcher[Book Searcher Service] + Searcher -- RabbitMQ --> SearcherAgent[Book Searcher Agent] + SearcherAgent -- HTTP --> Websites[(External Websites)] + Server -- MongoDB --> Database[(MongoDB Database)] + Searcher -- MongoDB --> Database + SearcherAgent -- MongoDB --> Database ``` -```shell -protoc --go-grpc_out=. librakeeper-server/pkg/pb/book.proto -``` \ No newline at end of file +## Getting Started + +Here's how to set up and run Librakeeper Server locally: + +### Prerequisites + +* **Go:** [https://golang.org/](https://golang.org/) +* **Docker:** [https://www.docker.com/](https://www.docker.com/) +* **Docker Compose:** [https://docs.docker.com/compose/](https://docs.docker.com/compose/) +* **MongoDB:** [https://www.mongodb.com/](https://www.mongodb.com/) + +### Configuration + +1. **Configuration Files:** + - Configure the server, searcher, and searcher-agent microservices using the provided YAML configuration files ( + e.g., `config/server/docker-local.yaml`). + - Update database connection details, RabbitMQ settings, and other relevant parameters in these files. +2. **Firebase Credentials:** + - Obtain Firebase service account credentials (a JSON file). + - Place the credentials file in the `config/server` directory and reference it in the server's configuration + file (`auth.config_path`). + +### Installation + +1. **Clone the Repository:** + ```bash + git clone https://github.com/your-username/librakeeper-server.git + cd librakeeper-server + ``` +2. **Start Services:** + ```bash + docker-compose up -d + ``` + +### Running the Server + +Once the services are up and running, the Librakeeper Server will be accessible at `http://localhost:8080`.