# raviwarrier/audiobookshelf-quick-bookmarks architecture

> Architecture diagram of the GitHub repository raviwarrier/audiobookshelf-quick-bookmarks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raviwarrier/audiobookshelf-quick-bookmarks
- Repository: https://github.com/raviwarrier/audiobookshelf-quick-bookmarks

## Overview

Audiobookshelf Quick Bookmarks is a stateless FastAPI trigger service: a mobile or webhook caller sends a bookmark request with the user’s Audiobookshelf token; the service can discover the user’s active unfinished item and playback position, create the bookmark in Audiobookshelf, and return confirmation. The README also documents optional shared-key protection and explicit item/time inputs. Sampled backend code supports the main request flow; the frontend is an empty React shell, so it is not part of this workflow.

Main entry points: [`main.py`](https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py) (Bookmark endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trigger["Trigger API"]
  node_handler["Bookmark endpoint<br/>[main.py]"]
  node_health["Health / info<br/>[main.py]"]
end

subgraph group_workflow["Bookmark Workflow"]
  node_progress_query["Progress lookup<br/>[main.py]"]
  node_active_item["Active-item selection<br/>[main.py]"]
  node_bookmark_request["Bookmark request<br/>[main.py]"]
  node_confirmation["Bookmark confirmation<br/>[main.py]"]
end

subgraph group_security["Request Security"]
  node_service_key["Service-key check<br/>[main.py]"]
  node_user_token["User-token extraction<br/>[main.py]"]
end

node_caller(("Mobile / webhook"))
node_abs["Audiobookshelf"]

node_caller -->|"POST request"| node_handler
node_handler -->|"checks key"| node_service_key
node_handler -->|"resolves token"| node_user_token
node_handler -->|"looks up progress"| node_progress_query
node_progress_query -->|"GET progress"| node_abs
node_abs -->|"returns progress"| node_active_item
node_handler -->|"selects item"| node_active_item
node_handler -->|"submits bookmark"| node_bookmark_request
node_bookmark_request -->|"POST bookmark"| node_abs
node_abs -->|"returns result"| node_confirmation
node_handler -->|"formats response"| node_confirmation
node_caller -->|"GET status"| node_health

click node_handler "https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py"
click node_health "https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py"
click node_service_key "https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py"
click node_user_token "https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py"
click node_progress_query "https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py"
click node_active_item "https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py"
click node_bookmark_request "https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py"
click node_confirmation "https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_handler,node_health toneBlue
class node_progress_query,node_active_item,node_bookmark_request,node_confirmation toneAmber
class node_service_key,node_user_token,node_caller toneMint
class node_abs toneIndigo
```

## Components

### Trigger API

- [Bookmark endpoint](https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py): `main.py`
- [Health / info](https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py): `main.py`

### Bookmark Workflow

- [Progress lookup](https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py): `main.py`
- [Active-item selection](https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py): `main.py`
- [Bookmark request](https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py): `main.py`
- [Bookmark confirmation](https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py): `main.py`

### Request Security

- [Service-key check](https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py): `main.py`
- [User-token extraction](https://github.com/raviwarrier/audiobookshelf-quick-bookmarks/blob/main/main.py): `main.py`

### Other components

- **Mobile / webhook**
- **Audiobookshelf**

## Connections

- Mobile / webhook → Bookmark endpoint: POST request
- Bookmark endpoint → Service-key check: checks key
- Bookmark endpoint → User-token extraction: resolves token
- Bookmark endpoint → Progress lookup: looks up progress
- Progress lookup → Audiobookshelf: GET progress
- Audiobookshelf → Active-item selection: returns progress
- Bookmark endpoint → Active-item selection: selects item
- Bookmark endpoint → Bookmark request: submits bookmark
- Bookmark request → Audiobookshelf: POST bookmark
- Audiobookshelf → Bookmark confirmation: returns result
- Bookmark endpoint → Bookmark confirmation: formats response
- Mobile / webhook → Health / info: GET status