enhance README files

getz-devs · Jul 21, 2024 · f9442b7 · f9442b7
1 parent 78e11e0
commit f9442b7
Show file tree

Hide file tree

Showing 2 changed files with 218 additions and 6 deletions.
diff --git a/API.md 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 <token>`
+
+### 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
@@ -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
-```
+## 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`.