# 1younesalloui/booklib architecture

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

- Interactive diagram: https://gitdiagram.com/1younesalloui/booklib
- Repository: https://github.com/1younesalloui/booklib

## Overview

BookLib’s mobile workflow is discover/search → inspect a title → save or update its reading status, rating, and review; a separate chat offers shelf-aware AI assistance. Django serves discovery, shelf, and chat APIs, with book and shelf records persisted in relational models. The README documents multi-provider aggregation, filtering, pagination, caching, and deduplication, though provider and cache internals are only partially sampled. Edges for those documented backend behaviors use the sampled views file; unsampled UI/API wiring is omitted where no relationship is evidenced.

Main entry points: [`backend/bookrating/app/views.py`](https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/views.py) (API handlers), [`frontend/src/services/api.ts`](https://github.com/1younesalloui/booklib/blob/main/frontend/src/services/api.ts) (API client), [`frontend/src/app/index.tsx`](https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/index.tsx) (Home feed), [`frontend/src/app/explore.tsx`](https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/explore.tsx) (Explore search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_discover["Home feed<br/>[index.tsx]"]
  node_search["Explore search<br/>[explore.tsx]"]
  node_library["Personal library<br/>[library.tsx]"]
  node_chat_ui["AI chat<br/>[chat.tsx]"]
  node_detail["Book details"]
  node_card["Book cards<br/>[BookCard.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_theme["Theme preferences<br/>[index.ts]"]
end

subgraph group_api["Backend API"]
  node_router["API routing<br/>[urls.py]"]
  node_handlers["API handlers<br/>[views.py]"]
  node_validation["Request serializers<br/>[serializers.py]"]
  node_ai_engine["AI response engine<br/>[ai_engine.py]"]
end

subgraph group_domain["Books and shelves"]
  node_books[("Book records<br/>[models.py]")]
  node_shelves[("Shelf records<br/>[models.py]")]
end

subgraph group_integrations["External services"]
  node_providers["Book providers<br/>[views.py]"]
  node_groq["Groq AI"]
  node_database[("SQL database")]
end

node_reader(("Reader"))

node_reader -->|"browses"| node_discover
node_reader -->|"searches"| node_search
node_reader -->|"manages shelf"| node_library
node_reader -->|"chats"| node_chat_ui
node_discover -->|"loads feed"| node_api_client
node_search -->|"searches books"| node_api_client
node_library -->|"loads shelf"| node_api_client
node_detail -->|"updates shelf"| node_api_client
node_api_client -->|"sends requests"| node_router
node_router -->|"routes requests"| node_handlers
node_handlers -->|"validates chat"| node_validation
node_handlers -->|"reads and writes"| node_books
node_handlers -->|"reads and writes"| node_shelves
node_handlers -->|"aggregates titles"| node_providers
node_providers -.->|"supplies metadata"| node_books
node_chat_ui -.->|"uses chat API"| node_api_client
node_api_client -.->|"requests chat"| node_handlers
node_handlers -->|"gets response"| node_ai_engine
node_ai_engine -->|"calls model"| node_groq
node_ai_engine -.->|"uses shelf context"| node_shelves
node_books -.->|"persists"| node_database
node_shelves -.->|"persists"| node_database
node_discover -->|"renders titles"| node_card
node_search -->|"renders results"| node_card
node_library -->|"renders shelf"| node_card
node_discover -->|"opens title"| node_detail
node_search -->|"opens title"| node_detail
node_library -->|"opens title"| node_detail
node_theme -.->|"stores preference"| node_database

click node_discover "https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/index.tsx"
click node_search "https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/explore.tsx"
click node_library "https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/library.tsx"
click node_chat_ui "https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/chat.tsx"
click node_detail "https://github.com/1younesalloui/booklib/blob/main/frontend/src/components/BookDetailModal.tsx"
click node_card "https://github.com/1younesalloui/booklib/blob/main/frontend/src/components/BookCard.tsx"
click node_api_client "https://github.com/1younesalloui/booklib/blob/main/frontend/src/services/api.ts"
click node_theme "https://github.com/1younesalloui/booklib/blob/main/frontend/src/theme/index.ts"
click node_router "https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/urls.py"
click node_handlers "https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/views.py"
click node_validation "https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/serializers.py"
click node_ai_engine "https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/ai_engine.py"
click node_books "https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/models.py"
click node_shelves "https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/models.py"
click node_providers "https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/views.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_discover,node_search,node_library,node_chat_ui,node_detail,node_card,node_api_client,node_theme toneBlue
class node_router,node_handlers,node_validation,node_ai_engine toneAmber
class node_books,node_shelves toneMint
class node_providers,node_groq,node_database toneRose
class node_reader toneIndigo
```

## Components

### Mobile app

- [Home feed](https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/index.tsx): `frontend/src/app/index.tsx`
- [Explore search](https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/explore.tsx): `frontend/src/app/explore.tsx`
- [Personal library](https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/library.tsx): `frontend/src/app/library.tsx`
- [AI chat](https://github.com/1younesalloui/booklib/blob/main/frontend/src/app/chat.tsx): `frontend/src/app/chat.tsx`
- [Book details](https://github.com/1younesalloui/booklib/blob/main/frontend/src/components/BookDetailModal.tsx): `frontend/src/components/BookDetailModal.tsx`
- [Book cards](https://github.com/1younesalloui/booklib/blob/main/frontend/src/components/BookCard.tsx): `frontend/src/components/BookCard.tsx`
- [API client](https://github.com/1younesalloui/booklib/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Theme preferences](https://github.com/1younesalloui/booklib/blob/main/frontend/src/theme/index.ts): `frontend/src/theme/index.ts`

### Backend API

- [API routing](https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/urls.py): `backend/bookrating/app/urls.py`
- [API handlers](https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/views.py): `backend/bookrating/app/views.py`
- [Request serializers](https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/serializers.py): `backend/bookrating/app/serializers.py`
- [AI response engine](https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/ai_engine.py): `backend/bookrating/app/ai_engine.py`

### Books and shelves

- [Book records](https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/models.py): `backend/bookrating/app/models.py`
- [Shelf records](https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/models.py): `backend/bookrating/app/models.py`

### External services

- [Book providers](https://github.com/1younesalloui/booklib/blob/main/backend/bookrating/app/views.py): `backend/bookrating/app/views.py`
- **Groq AI**
- **SQL database**

### Other components

- **Reader**

## Connections

- Reader → Home feed: browses (evidence: `README.md`)
- Reader → Explore search: searches (evidence: `README.md`)
- Reader → Personal library: manages shelf (evidence: `README.md`)
- Reader → AI chat: chats (evidence: `README.md`)
- Home feed → API client: loads feed (evidence: `frontend/src/app/index.tsx`)
- Explore search → API client: searches books (evidence: `frontend/src/app/explore.tsx`)
- Personal library → API client: loads shelf (evidence: `README.md`)
- Book details → API client: updates shelf (evidence: `frontend/src/components/BookDetailModal.tsx`)
- API client → API routing: sends requests (evidence: `README.md`)
- API routing → API handlers: routes requests (evidence: `backend/bookrating/app/urls.py`)
- API handlers → Request serializers: validates chat (evidence: `backend/bookrating/app/views.py`)
- API handlers → Book records: reads and writes (evidence: `backend/bookrating/app/views.py`)
- API handlers → Shelf records: reads and writes (evidence: `backend/bookrating/app/views.py`)
- API handlers → Book providers: aggregates titles (evidence: `README.md`)
- Book providers → Book records: supplies metadata (evidence: `backend/bookrating/app/views.py`)
- AI chat → API client: uses chat API (evidence: `frontend/src/app/chat.tsx`)
- API client → API handlers: requests chat
- API handlers → AI response engine: gets response (evidence: `backend/bookrating/app/views.py`)
- AI response engine → Groq AI: calls model (evidence: `backend/bookrating/app/ai_engine.py`)
- AI response engine → Shelf records: uses shelf context
- Book records → SQL database: persists
- Shelf records → SQL database: persists
- Home feed → Book cards: renders titles (evidence: `frontend/src/app/index.tsx`)
- Explore search → Book cards: renders results (evidence: `frontend/src/app/explore.tsx`)
- Personal library → Book cards: renders shelf (evidence: `README.md`)
- Home feed → Book details: opens title (evidence: `frontend/src/app/index.tsx`)
- Explore search → Book details: opens title (evidence: `README.md`)
- Personal library → Book details: opens title (evidence: `README.md`)
- Theme preferences → SQL database: stores preference
