# raghavtandonn/goodreads-shelf-analytics-api architecture

> Architecture diagram of the GitHub repository raghavtandonn/goodreads-shelf-analytics-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raghavtandonn/goodreads-shelf-analytics-api
- Repository: https://github.com/raghavtandonn/goodreads-shelf-analytics-api
- Video tour (about a minute): https://gitdiagram.com/raghavtandonn/goodreads-shelf-analytics-api/video

## Overview

This FastAPI service imports a Goodreads CSV into a local book-and-reading library, reports reading statistics, and ranks to-read books with score explanations. The main workflow is upload, validate and normalize CSV data, upsert the user’s books and readings, then query that library for analytics or recommendations. The recommendation path builds preferences from rated reads and scores to-read candidates. Source excerpts support these links; the tree and README identify the service’s capabilities, but do not document additional integrations.

Main entry points: [`main.py`](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/main.py) (FastAPI routes), [`services/recommend.py`](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/recommend.py) (Recommendation service), [`database.py`](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/database.py) (SQLAlchemy database), [`services/etl.py`](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/etl.py) (CSV validation and upsert)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_main["FastAPI routes<br/>[main.py]"]
  node_stats["Overview statistics<br/>[main.py]"]
end

subgraph group_import["CSV Import"]
  node_etl["CSV validation and upsert<br/>[etl.py]"]
end

subgraph group_recommend["Recommendations"]
  node_recommend_service["Recommendation service<br/>[recommend.py]"]
  node_profile["Taste profile<br/>[recommend.py]"]
  node_candidates["To-read candidates<br/>[recommend.py]"]
  node_scoring["Scoring and explanations<br/>[recommend.py]"]
end

subgraph group_data["Library Data"]
  node_models["User, Book, Reading<br/>[models.py]"]
  node_database[("SQLAlchemy database<br/>[database.py]")]
end

node_reader(("Library owner"))
node_client(("API client"))
node_goodreads_csv["Goodreads CSV"]

node_reader -->|"exports"| node_goodreads_csv
node_client -->|"uploads CSV"| node_main
node_goodreads_csv -->|"file data"| node_main
node_main -->|"imports"| node_etl
node_etl -->|"creates and updates"| node_models
node_etl -->|"writes via session"| node_database
node_main -->|"creates tables and sessions"| node_database
node_client -->|"requests statistics"| node_main
node_main -->|"dispatches"| node_stats
node_stats -->|"queries readings and books"| node_database
node_client -->|"requests recommendations"| node_main
node_main -->|"calls"| node_recommend_service
node_recommend_service -->|"builds"| node_profile
node_profile -->|"queries rated reads"| node_database
node_recommend_service -->|"queries"| node_candidates
node_candidates -->|"reads to-read books"| node_database
node_recommend_service -->|"scores and sorts"| node_scoring
node_recommend_service -->|"returns ranked items"| node_main

click node_main "https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/main.py"
click node_etl "https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/etl.py"
click node_models "https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/models.py"
click node_database "https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/database.py"
click node_stats "https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/main.py"
click node_recommend_service "https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/recommend.py"
click node_profile "https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/recommend.py"
click node_candidates "https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/recommend.py"
click node_scoring "https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/recommend.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_main,node_stats,node_client toneBlue
class node_etl toneAmber
class node_recommend_service,node_profile,node_candidates,node_scoring toneMint
class node_models,node_database toneRose
class node_reader,node_goodreads_csv toneIndigo
```

## Components

### API

- [FastAPI routes](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/main.py): `main.py`
- [Overview statistics](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/main.py): `main.py`

### CSV Import

- [CSV validation and upsert](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/etl.py): `services/etl.py`

### Recommendations

- [Recommendation service](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/recommend.py): `services/recommend.py`
- [Taste profile](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/recommend.py): `services/recommend.py`
- [To-read candidates](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/recommend.py): `services/recommend.py`
- [Scoring and explanations](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/services/recommend.py): `services/recommend.py`

### Library Data

- [User, Book, Reading](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/models.py): `models.py`
- [SQLAlchemy database](https://github.com/raghavtandonn/goodreads-shelf-analytics-api/blob/main/database.py): `database.py`

### Other components

- **Library owner**
- **API client**
- **Goodreads CSV**

## Connections

- Library owner → Goodreads CSV: exports
- API client → FastAPI routes: uploads CSV
- Goodreads CSV → FastAPI routes: file data
- FastAPI routes → CSV validation and upsert: imports
- CSV validation and upsert → User, Book, Reading: creates and updates
- CSV validation and upsert → SQLAlchemy database: writes via session
- FastAPI routes → SQLAlchemy database: creates tables and sessions
- API client → FastAPI routes: requests statistics
- FastAPI routes → Overview statistics: dispatches
- Overview statistics → SQLAlchemy database: queries readings and books
- API client → FastAPI routes: requests recommendations
- FastAPI routes → Recommendation service: calls
- Recommendation service → Taste profile: builds
- Taste profile → SQLAlchemy database: queries rated reads
- Recommendation service → To-read candidates: queries
- To-read candidates → SQLAlchemy database: reads to-read books
- Recommendation service → Scoring and explanations: scores and sorts
- Recommendation service → FastAPI routes: returns ranked items