How raghavtandonn/goodreads-shelf-analytics-api works
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 FastAPI routes · recommend.py Recommendation service · database.py SQLAlchemy database · etl.py CSV validation and upsert
Components 12
API
- FastAPI routes
main.py - Overview statistics
main.py
CSV Import
- CSV validation and upsert
services/etl.py
Recommendations
- Recommendation service
services/recommend.py - Taste profile
services/recommend.py - To-read candidates
services/recommend.py - Scoring and explanations
services/recommend.py
Library Data
- User, Book, Reading
models.py - SQLAlchemy database
database.py
Other components
- Library owner
- API client
- Goodreads CSV
Connections 18
- 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