Transform your Goodreads library export into an interactive dashboard with rich analytics, genre insights, and reading visualizations.
- Reading Analytics - Track books read over time, by month and year
- Genre Enrichment - Automatic genre classification via Google Books and Open Library APIs
- Rating Analysis - Compare your ratings to community averages
- Book Details - Cover images, descriptions, and your personal notes
- Smart Filtering - Filter by genre, rating, year, or any combination
# Clone and start
git clone https://github.com/carsondavis/goodreads_stats.git
cd goodreads_stats
docker-compose up -d
# Open http://localhost:8000 and upload your Goodreads CSV export# Install dependencies with uv
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
# Start API server
uv run python local_server.py
# In another terminal, serve frontend
cd dashboard && python -m http.server 8000- Go to Goodreads Export
- Click "Export Library"
- Upload the CSV to the app
goodreads_stats/
├── genres/ # Core Python pipeline
│ ├── models/ # Data models (BookInfo, EnrichedBook, BookAnalytics)
│ ├── pipeline/ # CSV loading, enrichment, export
│ ├── sources/ # API clients (Google Books, Open Library)
│ └── utils/ # Shared utilities
├── dashboard/ # Static frontend (HTML/JS/CSS)
├── cdk/ # AWS CDK infrastructure
│ └── lambda_code/ # Lambda function handlers
├── local_server.py # FastAPI development server
├── docker-compose.yml # Local development setup
└── docs/ # Documentation
| Document | Description |
|---|---|
| Getting Started | Set up your development environment |
| Architecture | System overview and data flow |
| Data Models | BookInfo, EnrichedBook, BookAnalytics |
| API Reference | REST endpoint documentation |
| Lambda Functions | AWS Lambda handler details |
| Troubleshooting | Common issues and solutions |
Goodreads CSV Export
|
v
[Upload to System]
|
v
[Genre Enrichment] <-- Google Books API
| <-- Open Library API
v
[Dashboard JSON]
|
v
[Interactive Dashboard]
| Mode | Frontend | Processing | Storage |
|---|---|---|---|
| Local | nginx:8000 | FastAPI:8001 | dashboard_data/ |
| Cloud | S3 + CloudFront | AWS Lambda | S3 |
View a sample dashboard: Sample Dashboard
uv run python local_server.py
# API docs: http://localhost:8001/docsMIT