# audiobookshelf/audiobookshelf-client-react architecture

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

- Interactive diagram: https://gitdiagram.com/audiobookshelf/audiobookshelf-client-react
- Repository: https://github.com/audiobookshelf/audiobookshelf-client-react

## Overview

This repository is the Next.js web client for Audiobookshelf, intended to replace its Vue client. Users sign in, browse and search libraries, inspect and manage media, and listen through the shared player; administrators also configure server capabilities. The graph emphasizes those product areas and the sampled connections between them. Many routes and settings subsystems are represented by their existing directories because their implementations were not sampled; their internal wiring is therefore not asserted.

Main entry points: [`src/app/actions/mediaActions.ts`](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/actions/mediaActions.ts) (Media API actions), [`src/contexts/MediaContext.tsx`](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/contexts/MediaContext.tsx) (Media state), [`src/hooks/usePlayerHandler.ts`](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/hooks/usePlayerHandler.ts) (Player handler), [`src/lib/api.ts`](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and shell"]
  node_login["Login<br/>[LoginForm.tsx]"]
  node_app_shell["App shell<br/>[layout.tsx]"]
  node_user_context["User state<br/>[UserContext.tsx]"]
end

subgraph group_library["Library experience"]
  node_library_browse["Library browsing"]
  node_bookshelf_query["Shelf query"]
  node_library_state["Library state<br/>[LibraryContext.tsx]"]
  node_library_search["Library search<br/>[SearchClient.tsx]"]
  node_media_actions["Media actions"]
end

subgraph group_playback["Playback"]
  node_media_context["Media state<br/>[MediaContext.tsx]"]
  node_player_handler["Player handler"]
  node_playback_session["Playback session"]
  node_local_player["Local audio player"]
  node_player_ui["Player interface"]
end

subgraph group_administration["Administration"]
  node_settings["Server settings"]
  node_authentication_settings["Authentication settings"]
  node_authentication_actions["Authentication actions<br/>[actions.ts]"]
end

subgraph group_platform["Client platform"]
  node_media_api_actions["Media API actions<br/>[mediaActions.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_socket_context["Socket connection<br/>[SocketContext.tsx]"]
  node_types["API data types<br/>[api.ts]"]
end

node_user(("User"))
node_server_socket{{"Audiobookshelf server"}}

node_user -->|"signs in"| node_login
node_library_browse -.->|"uses query"| node_bookshelf_query
node_bookshelf_query -->|"updates settings"| node_library_state
node_library_search -->|"requests search"| node_media_api_actions
node_media_actions -->|"invokes actions"| node_media_api_actions
node_media_api_actions -->|"calls API"| node_api_client
node_media_context -->|"loads item"| node_media_api_actions
node_media_context -->|"uses handler"| node_player_handler
node_media_context -->|"renders player"| node_player_ui
node_player_handler -->|"manages session"| node_playback_session
node_player_handler -->|"uses backend"| node_local_player
node_socket_context -->|"connects to"| node_server_socket
node_user_context -->|"subscribes events"| node_socket_context
node_authentication_settings -->|"updates settings"| node_authentication_actions
node_authentication_actions -.->|"uses API"| node_api_client
node_api_client -.->|"requests server"| node_server_socket

click node_login "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(blank)/login/LoginForm.tsx"
click node_app_shell "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/layout.tsx"
click node_library_browse "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/library/%5Blibrary%5D/%5BentityType%5D/BookshelfClient.tsx"
click node_bookshelf_query "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/hooks/useBookshelfQuery.ts"
click node_library_state "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/contexts/LibraryContext.tsx"
click node_library_search "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/library/%5Blibrary%5D/search/SearchClient.tsx"
click node_media_actions "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/components/widgets/media-card/useMediaCardActions.ts"
click node_media_api_actions "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/actions/mediaActions.ts"
click node_api_client "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/lib/api.ts"
click node_media_context "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/contexts/MediaContext.tsx"
click node_player_handler "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/hooks/usePlayerHandler.ts"
click node_playback_session "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/hooks/usePlaybackSession.ts"
click node_local_player "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/lib/player/LocalAudioPlayer.ts"
click node_player_ui "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/components/player/MediaPlayerContainer.tsx"
click node_socket_context "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/contexts/SocketContext.tsx"
click node_user_context "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/contexts/UserContext.tsx"
click node_settings "https://github.com/audiobookshelf/audiobookshelf-client-react/tree/master/src/app/(main)/settings"
click node_authentication_settings "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/settings/authentication/AuthenticationClient.tsx"
click node_authentication_actions "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/settings/authentication/actions.ts"
click node_types "https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/types/api.ts"

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_login,node_app_shell,node_user_context,node_user toneBlue
class node_library_browse,node_bookshelf_query,node_library_state,node_library_search,node_media_actions toneAmber
class node_media_context,node_player_handler,node_playback_session,node_local_player,node_player_ui,node_server_socket toneMint
class node_settings,node_authentication_settings,node_authentication_actions toneRose
class node_media_api_actions,node_api_client,node_socket_context,node_types toneIndigo
```

## Components

### Identity and shell

- [Login](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(blank)/login/LoginForm.tsx): `src/app/(blank)/login/LoginForm.tsx`
- [App shell](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/layout.tsx): `src/app/(main)/layout.tsx`
- [User state](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/contexts/UserContext.tsx): `src/contexts/UserContext.tsx`

### Library experience

- [Library browsing](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/library/%5Blibrary%5D/%5BentityType%5D/BookshelfClient.tsx): `src/app/(main)/library/[library]/[entityType]/BookshelfClient.tsx`
- [Shelf query](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/hooks/useBookshelfQuery.ts): `src/hooks/useBookshelfQuery.ts`
- [Library state](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/contexts/LibraryContext.tsx): `src/contexts/LibraryContext.tsx`
- [Library search](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/library/%5Blibrary%5D/search/SearchClient.tsx): `src/app/(main)/library/[library]/search/SearchClient.tsx`
- [Media actions](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/components/widgets/media-card/useMediaCardActions.ts): `src/components/widgets/media-card/useMediaCardActions.ts`

### Playback

- [Media state](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/contexts/MediaContext.tsx): `src/contexts/MediaContext.tsx`
- [Player handler](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/hooks/usePlayerHandler.ts): `src/hooks/usePlayerHandler.ts`
- [Playback session](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/hooks/usePlaybackSession.ts): `src/hooks/usePlaybackSession.ts`
- [Local audio player](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/lib/player/LocalAudioPlayer.ts): `src/lib/player/LocalAudioPlayer.ts`
- [Player interface](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/components/player/MediaPlayerContainer.tsx): `src/components/player/MediaPlayerContainer.tsx`

### Administration

- [Server settings](https://github.com/audiobookshelf/audiobookshelf-client-react/tree/master/src/app/(main)/settings): `src/app/(main)/settings`
- [Authentication settings](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/settings/authentication/AuthenticationClient.tsx): `src/app/(main)/settings/authentication/AuthenticationClient.tsx`
- [Authentication actions](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/(main)/settings/authentication/actions.ts): `src/app/(main)/settings/authentication/actions.ts`

### Client platform

- [Media API actions](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/app/actions/mediaActions.ts): `src/app/actions/mediaActions.ts`
- [API client](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/lib/api.ts): `src/lib/api.ts`
- [Socket connection](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/contexts/SocketContext.tsx): `src/contexts/SocketContext.tsx`
- [API data types](https://github.com/audiobookshelf/audiobookshelf-client-react/blob/master/src/types/api.ts): `src/types/api.ts`

### Other components

- **User**
- **Audiobookshelf server**

## Connections

- User → Login: signs in
- Library browsing → Shelf query: uses query
- Shelf query → Library state: updates settings (evidence: `src/hooks/useBookshelfQuery.ts`)
- Library search → Media API actions: requests search (evidence: `src/app/(main)/library/[library]/search/SearchClient.tsx`)
- Media actions → Media API actions: invokes actions (evidence: `src/components/widgets/media-card/useMediaCardActions.ts`)
- Media API actions → API client: calls API (evidence: `src/app/actions/mediaActions.ts`)
- Media state → Media API actions: loads item (evidence: `src/contexts/MediaContext.tsx`)
- Media state → Player handler: uses handler (evidence: `src/contexts/MediaContext.tsx`)
- Media state → Player interface: renders player (evidence: `src/contexts/MediaContext.tsx`)
- Player handler → Playback session: manages session (evidence: `src/hooks/usePlayerHandler.ts`)
- Player handler → Local audio player: uses backend (evidence: `src/hooks/usePlayerHandler.ts`)
- Socket connection → Audiobookshelf server: connects to (evidence: `src/contexts/SocketContext.tsx`)
- User state → Socket connection: subscribes events (evidence: `src/contexts/UserContext.tsx`)
- Authentication settings → Authentication actions: updates settings (evidence: `src/app/(main)/settings/authentication/AuthenticationClient.tsx`)
- Authentication actions → API client: uses API
- API client → Audiobookshelf server: requests server
