# Books V2

_Last updated: 2025-12-13_

`#docker #app #books-v2`

## Architecture Overview

Books V2 is a web application for tracking books read. It consists of a React frontend and a FastAPI backend.

-   **Frontend:** The frontend is a single-page application built with [React](https://react.dev/) and [Vite](https://vitejs.dev/). It uses [TypeScript](https://www.typescriptlang.org/) for static typing, [Tailwind CSS](https://tailwindcss.com/) for styling, and [TanStack Query](https://tanstack.com/query/latest) for data fetching and caching.
-   **Backend:** The backend is a RESTful API built with [FastAPI](https://fastapi.tiangolo.com/), a modern, high-performance Python web framework. It uses [SQLAlchemy](https://www.sqlalchemy.org/) as the ORM to interact with the database.
-   **Database:** The application uses a [MySQL](https://www.mysql.com/) database to store all its data. [Alembic](https://alembic.sqlalchemy.org/) is used for database migrations.

## API Endpoints

The API is versioned and all endpoints are available under the `/api/v1` prefix.

### Authentication

-   `GET /me`: Get the current authenticated user's information.
-   `GET /users`: Get a list of all users.

### Books

-   `GET /books`: Get a paginated list of books.
    -   Query Parameters: `page`, `items_per_page`, `search`, `year`, `sort_by`, `sort_order`, `view_as_user_id`
-   `POST /books`: Create a new book.
-   `GET /books/{book_id}`: Get a single book by ID.
-   `PUT /books/{book_id}`: Update a book by ID.
-   `DELETE /books/{book_id}`: Delete a book by ID.
-   `POST /books/from-next/{next_book_id}`: Create a new book from a "next book".

### Next Books

-   `GET /next-books`: Get a paginated list of books in the "to read" list.
    -   Query Parameters: `page`, `items_per_page`, `search`, `sort_by`, `sort_order`, `view_as_user_id`
-   `POST /next-books`: Add a new book to the "to read" list.
-   `PUT /next-books/bulk-update-order`: Bulk update the reading order of the "to read" list.
-   `GET /next-books/{book_id}`: Get a single "next book" by ID.
-   `PUT /next-books/{book_id}`: Update a "next book" by ID.
-   `DELETE /next-books/{book_id}`: Delete a "next book" by ID.

### Autocomplete

-   `GET /autocomplete/formats`: Get a list of all unique book formats.
-   `GET /autocomplete/authors`: Get a list of all unique authors.
-   `GET /autocomplete/genres`: Get a list of all unique genres.

### Summary

-   `GET /summary/all`: Get a summary of all books.
-   `GET /summary/audiobooks`: Get a summary of all audiobooks.
-   `GET /summary/non-audiobooks`: Get a summary of all non-audiobooks.
-   `GET /summary/yearly`: Get a yearly summary of reading stats.

### Advanced Stats

-   `GET /advanced-stats`: Get advanced reading statistics.

### Search

-   `GET /search`: Search for books using an external API (Google Books).
    -   Query Parameters: `query`, `max_results`

## Database Schema

The database consists of three main tables: `users`, `books`, and `next_books`.

### `users` table

| Column         | Type         | Constraints              |
|----------------|--------------|--------------------------|
| `id`           | `Integer`    | Primary Key, Autoincrement |
| `username`     | `String(255)`| Not Null, Unique, Indexed|
| `email`        | `String(255)`| Nullable                 |
| `display_name` | `String(255)`| Nullable                 |
| `created_at`   | `DateTime`   | Not Null, Server Default |
| `last_login`   | `DateTime`   | Nullable                 |

### `books` table

| Column          | Type         | Constraints                              |
|-----------------|--------------|------------------------------------------|
| `id`            | `Integer`    | Primary Key, Autoincrement               |
| `user_id`       | `Integer`    | Foreign Key (`users.id`), Not Null, Indexed |
| `format`        | `String(50)` | Not Null                                 |
| `title`         | `String(255)`| Not Null                                 |
| `author`        | `String(255)`| Nullable                                 |
| `genre`         | `String(255)`| Nullable                                 |
| `date_started`  | `Date`       | Not Null                                 |
| `date_finished` | `Date`       | Nullable                                 |
| `days`          | `Integer`    | Nullable                                 |
| `pages`         | `Integer`    | Not Null                                 |
| *Unique*        |              | `user_id`, `title`                       |

### `next_books` table

| Column           | Type         | Constraints                              |
|------------------|--------------|------------------------------------------|
| `id`             | `Integer`    | Primary Key, Autoincrement               |
| `user_id`        | `Integer`    | Foreign Key (`users.id`), Not Null, Indexed |
| `title`          | `String(255)`| Not Null                                 |
| `author`         | `String(255)`| Not Null                                 |
| `genre`          | `String(255)`| Nullable                                 |
| `pages`          | `Integer`    | Nullable                                 |
| `format`         | `String(255)`| Nullable                                 |
| `purchased_status`|`Boolean`    | Nullable, Default: `False`               |
| `reading_order`  | `Integer`    | Nullable                                 |
| *Unique*         |              | `user_id`, `title`                       |

## Authentication

Authentication is handled by the Traefik reverse proxy in conjunction with Authelia. Authelia is an authentication and authorization server that provides single sign-on (SSO) for web applications.

When a user accesses the Books V2 application, Traefik forwards the request to Authelia for authentication. If the user is not authenticated, Authelia presents a login page. Once the user authenticates, Authelia sets a `Remote-User` header in the request and forwards it to the Books V2 backend.

The backend's `get_current_user` dependency reads the `Remote-User` header, and then gets or creates the user in the database. This means that user management is handled by Authelia, and the Books V2 application trusts the `Remote-User` header set by the proxy.

## Environment Variables

### Backend (`.env`)

-   `DB_USER`: The username for the MySQL database.
-   `DB_PASSWORD`: The password for the MySQL database.
-   `DB_HOST`: The hostname or IP address of the MySQL database server.
-   `DB_PORT`: The port of the MySQL database server.
-   `DB_NAME`: The name of the MySQL database.
-   `DB_CHARSET`: The character set for the MySQL database connection.
-   `TZ`: The timezone for the application.

### Frontend (`.env`)

-   `VITE_API_URL`: The base URL for the backend API.

## Development Workflow

### Frontend

-   **Start dev server:** `npm run dev`
-   **Build for production:** `npm run build`
-   **Run tests:** No tests are currently configured.
-   **View logs:** Logs are printed to the console where the dev server is running.
-   **Access container shell:** `docker exec -it books_frontend /bin/sh`

### Backend

-   **Start dev server:** The backend is run directly via `uvicorn` in the `Dockerfile`, so there is no separate dev server command.
-   **Run tests:** No tests are currently configured.
-
-   **View logs:** `docker logs -f books_backend`
-   **Access container shell:** `docker exec -it books_backend /bin/bash`
-   **Database migrations:** Migrations are handled by Alembic. To create a new migration, run `alembic revision --autogenerate -m "Your migration message"`. To apply migrations, run `alembic upgrade head`.

## Deployment Process

The application is deployed using Docker Compose. The `docker-compose.yml` file defines two services: `frontend` and `backend`.

To deploy the application, run `docker-compose up -d --build`. This will build the Docker images for the frontend and backend and start the containers.

## Common Tasks

-   **Adding a new API endpoint:**
    1.  Add a new function to `backend/app/api/v1/endpoints/books.py`.
    2.  Add a new function to `frontend/src/utils/api.ts` to call the new endpoint.
    3.  Use the new function in a React component.
-   **Adding a new database table:**
    1.  Create a new model in `backend/app/models`.
    2.  Run `alembic revision --autogenerate -m "Add new table"` to create a new migration.
    3.  Run `alembic upgrade head` to apply the migration.

## Known Issues

-   No tests are configured for either the frontend or the backend.
-   The "Required by" field in the service inventory is not populated.

## File Structure

### Frontend

```
frontend/
├── public/              # Static assets
├── src/
│   ├── components/      # Reusable React components
│   ├── hooks/           # Custom React hooks
│   ├── lib/             # Library code (e.g., axios configuration)
│   ├── pages/           # Application pages
│   ├── stores/          # Zustand state management stores
│   ├── types/           # TypeScript type definitions
│   └── utils/           # Utility functions
├── Dockerfile.prod      # Production Dockerfile
├── package.json         # NPM dependencies and scripts
└── vite.config.ts       # Vite configuration
```

### Backend

```
backend/
├── alembic/              # Alembic database migration files
├── app/
│   ├── api/              # API endpoint definitions
│   ├── db/               # Database session management
│   ├── dependencies/     # FastAPI dependencies (e.g., auth)
│   ├── middleware/       # Custom middleware
│   ├── models/           # SQLAlchemy database models
│   ├── schemas/          # Pydantic data validation schemas
│   ├── services/         # Business logic
│   ├── config.py         # Application configuration
│   └── main.py           # Main FastAPI application
├── Dockerfile            # Dockerfile for the backend
└── requirements.txt      # Python dependencies
```