A decentralized, collaborative bookshelf platform with Bluesky (AT-Proto) authentication. Users can create and manage collections of books, set privacy levels, and collaborate with others through role-based permissions.

• Bookshelf Creation & Management: Create named bookshelves with unique URLs
• Advanced Search: Search shelves by name, description, and contained books (title, author, ISBN)
• Book Search & Addition: Integrated Google Books API for rich book metadata
• Upvoting System: Community-driven book curation through upvotes
• Privacy Controls: Public, Link-only, and Private bookshelf options
• Role-Based Permissions: Owner, Admin, Editor, and Viewer roles

• Network Activity Feed: See recent activity from users you follow on Bluesky
• Explore Page: Browse all public bookshelves in the community
• Community Reading Section: Discover recently added books from public shelves

• Bluesky Authentication: Secure login via AT-Proto
• User Profiles: Display names, handles, and avatars from Bluesky
• Session Management: Persistent login sessions

• Invite System: Generate invite links with role assignments and expiration
• Member Management: Add, remove, and manage member permissions
• Privacy Settings: Dynamic privacy level changes

• Responsive Design: Mobile-friendly interface with PicoCSS
• Interactive Book Cards: Clickable books linking to Google Books
• Real-time Search: HTMX-powered book search with instant results
• Unified Management: Combined edit, share, and delete interface
• Delete Confirmation: Type-to-confirm deletion for safety

• Advanced Search: Implemented hybrid search for shelves and books (title, author, ISBN)
• Network Activity Feed: Added a social feed based on Bluesky connections
• Community Discovery: New "Explore" page and community reading sections
• Enhanced Navigation: Integrated search and discovery into the main navigation
• Improved UI/UX: Redesigned search page, better empty states, and clearer titles
• Fixed Table Name Bug: Resolved database query errors in search

• Backend & Frontend: FastHTML
• Authentication: AT-Proto (Bluesky)
• Database: SQLite with FastLite + FastMigrate
• APIs: Google Books API
• Styling: PicoCSS + Custom CSS
• JavaScript: HTMX for dynamic interactions

Bibliome uses fastmigrate for database schema management, providing version control for your database structure and safe schema evolution.

FastMigrate follows the standard database migration pattern:

• Migration scripts define database versions (e.g., 0001-initialize.sql, 0002-add-feature.sql)
• Automatic application of pending migrations on startup
• Version tracking ensures each migration runs exactly once
• Safe evolution from any previous version to the latest

Migration scripts are stored in the migrations/ directory:

migrations/
└── 0001-initialize.sql    # Initial database schema

Each migration file:

• Must be numbered sequentially (0001, 0002, 0003, etc.)
• Should have a descriptive name after the number
• Contains SQL statements to modify the database
• Runs exactly once when the application starts

The initial migration (0001-initialize.sql) creates all necessary tables:

• user - Bluesky user profiles and authentication data
• bookshelf - Book collections with privacy and metadata
• book - Individual books with metadata from Google Books API
• permission - Role-based access control for bookshelves
• bookshelf_invite - Invitation system for sharing
• upvote - User votes on books for curation
• activity - Tracks user actions for the social feed

When you need to modify the database schema:

1. Create a new migration file in the migrations/ directory:

   # Example: Adding a new column to the book table
   touch migrations/0002-add-book-rating.sql

2. Write the SQL changes:

   -- migrations/0002-add-book-rating.sql
   -- Add rating column to books table
   
   ALTER TABLE book ADD COLUMN rating INTEGER DEFAULT 0;
   CREATE INDEX idx_book_rating ON book(rating);

3. Test the migration:

   # The migration will run automatically when you start the app
   python app.py

4. Verify the changes:

   # Check current database version
   python -c "from fastmigrate.core import get_db_version; print(f'Database version: {get_db_version(\"data/bookdit.db\")}')"

• Always backup your database before running migrations in production
• Test migrations on a copy of production data first
• Use descriptive names for migration files
• Keep migrations small and focused on one change
• Add indexes for new columns that will be queried
• Use transactions for complex multi-step migrations

• Never modify existing migration files once they've been applied
• Don't skip version numbers (use sequential numbering)
• Avoid destructive operations without careful consideration
• Don't mix schema and data changes in the same migration

FastMigrate provides command-line tools for database management:

# Check current database version
fastmigrate_check_version --db data/bookdit.db

# Create a new managed database (if needed)
fastmigrate_create_db --db data/bookdit.db

# Run pending migrations manually
fastmigrate_run_migrations --db data/bookdit.db --migrations migrations/

# Check what migrations would run
ls migrations/ | sort

-- migrations/0002-add-book-reviews.sql
-- Add book reviews functionality

CREATE TABLE book_review (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    book_id INTEGER NOT NULL,
    user_did TEXT NOT NULL,
    rating INTEGER NOT NULL CHECK (rating >= 1 AND rating <= 5),
    review_text TEXT DEFAULT '',
    created_at DATETIME,
    updated_at DATETIME,
    FOREIGN KEY (book_id) REFERENCES book(id),
    FOREIGN KEY (user_did) REFERENCES user(did)
);

CREATE INDEX idx_book_review_book ON book_review(book_id);
CREATE INDEX idx_book_review_user ON book_review(user_did);
CREATE INDEX idx_book_review_rating ON book_review(rating);

-- migrations/0003-normalize-book-authors.sql
-- Split author field into separate authors table

CREATE TABLE book_author (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    book_id INTEGER NOT NULL,
    author_name TEXT NOT NULL,
    author_order INTEGER DEFAULT 1,
    FOREIGN KEY (book_id) REFERENCES book(id)
);

-- Migrate existing author data
INSERT INTO book_author (book_id, author_name, author_order)
SELECT id, author, 1 
FROM book 
WHERE author IS NOT NULL AND author != '';

CREATE INDEX idx_book_author_book ON book_author(book_id);
CREATE INDEX idx_book_author_name ON book_author(author_name);

If a migration fails:

1. Check the error message in the application logs
2. Fix the SQL syntax in the migration file
3. Restore from backup if the database is corrupted
4. Test the fixed migration on a copy first

If you see version-related errors:

# Check current version
fastmigrate_check_version --db data/bookdit.db

# List available migrations
ls -la migrations/

# Manually run migrations if needed
fastmigrate_run_migrations --db data/bookdit.db --migrations migrations/

FastMigrate doesn't support automatic rollbacks, but you can:

1. Create a new migration that reverses the changes
2. Restore from a backup taken before the migration
3. Manually fix the database if the change was small

For production deployments:

1. Backup the database before deploying:

   cp data/bookdit.db data/bookdit.db.backup.$(date +%Y%m%d_%H%M%S)

2. Test migrations on a copy of production data first

3. Deploy with automatic migrations:

   • Migrations run automatically when the application starts
   • Monitor logs for migration success/failure
   • Have a rollback plan ready

4. Verify the deployment:

   # Check database version after deployment
   fastmigrate_check_version --db data/bookdit.db

• Python 3.8+
• A Google Books API key
• A Bluesky account for testing

1. Clone the repository

   git clone <repository-url>
   cd Bibliome

2. Install dependencies

   pip install -r requirements.txt

3. Configure environment variables

   cp .env.example .env

   Edit .env and add your configuration:

   # Bluesky/AT-Proto Configuration
   BLUESKY_HANDLE=your-handle.bsky.social
   BLUESKY_PASSWORD=your-app-password
   
   # Google Books API
   GOOGLE_BOOKS_API_KEY=your-google-books-api-key
   
   # Application Settings
   SECRET_KEY=your-secret-key-here
   DEBUG=true
   HOST=localhost
   PORT=5001
   BASE_URL=http://0.0.0.0:5001/

4. Run the application

   python app.py

5. Access the application Open your browser to http://localhost:5001

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Books API
4. Create credentials (API Key)
5. Add the API key to your .env file

1. Log into Bluesky
2. Go to Settings → Privacy and Security → App Passwords
3. Generate a new app password
4. Use your handle and app password in the .env file

1. Login with your Bluesky account
2. Click "Create New Shelf" on the homepage
3. Fill in details:
   • Name: Give your bookshelf a descriptive name
   • Description: Optional description of what the shelf is about
   • Privacy: Choose who can see your shelf
4. Click "Create Bookshelf"

1. Navigate to your bookshelf
2. Use the search box to find books by title, author, or ISBN
3. Click "Add to Shelf" on any search result
4. Books appear immediately in your collection

• Explore Page: Click "Explore" in the navigation to browse all public bookshelves.
• Search Page: Click "Search" to find specific shelves.
  • Use the main search bar to search by shelf name, description, or contained books.
  • Click "Advanced Search" to filter by specific book titles, authors, or ISBNs.
• Network Feed: On your dashboard, see shelves recently created or added to by people you follow on Bluesky.

1. Click "Manage" on any bookshelf you own or have admin access to
2. Edit Details: Change name, description, or privacy settings
3. Share & Members:
   • Generate invite links with specific roles
   • Manage existing members and their permissions
   • View pending invitations
4. Delete Shelf (owners only): Permanently delete with confirmation

1. Go to the Manage page of your bookshelf
2. In the Share & Members section, set:
   • Role for new members (Viewer, Editor, Admin)
   • Expiration time (optional)
   • Maximum uses (optional)
3. Generate Invite Link and share it

• Owner: Full control, can delete shelf
• Admin: Manage members, edit shelf, add books
• Editor: Add books and upvote
• Viewer: View books only

• Public: Anyone can find and view your bookshelf
• Link-only: Only people with the direct link can view
• Private: Only invited members can view

• User: Bluesky user profiles and authentication data
• Bookshelf: Book collections with privacy and metadata
• Book: Individual books with metadata from Google Books API
• Permission: Role-based access control for bookshelves
• BookshelfInvite: Invitation system for sharing
• Upvote: User votes on books for curation
• Activity: Tracks user actions for the social feed

• Authentication (auth.py): Bluesky AT-Proto integration
• API Clients (api_clients.py): Google Books API wrapper
• Models (models.py): Database models and business logic
• Components (components.py): Reusable UI components
• Main App (app.py): FastHTML routes and application logic

Bibliome/
├── app.py              # Main application
├── auth.py             # Authentication logic
├── api_clients.py      # External API integrations
├── models.py           # Database models
├── components.py       # UI components
├── requirements.txt    # Python dependencies
├── .env.example        # Environment template
├── static/
│   └── css/
│       └── styles.css  # Custom styling
└── data/               # SQLite database storage

python test_basic.py

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

• Verify your API key is correct in .env
• Check that the Books API is enabled in Google Cloud Console
• Ensure you haven't exceeded API quotas

• Check the console for API errors
• Verify your internet connection
• Try different search terms (title, author, ISBN)

• Ensure BASE_URL is set correctly in .env
• Check that the invite hasn't expired or reached max uses
• Verify the bookshelf privacy settings

• Verify your Bluesky handle and app password
• Check that you're using an app password, not your main password
• Ensure the Bluesky service is accessible

DEBUG=false
HOST=0.0.0.0
PORT=5001
BASE_URL=https://yourdomain.com/
SECRET_KEY=your-production-secret-key

• Use a strong, unique SECRET_KEY in production
• Enable HTTPS for production deployments
• Regularly rotate API keys
• Monitor for unusual activity

• Export/Import: Backup and restore bookshelves
• Enhanced Search: Filter by genre, publication date, etc.
• Reading Lists: Track reading progress and status (e.g., "To Read", "Reading", "Read")
• Book Reviews & Ratings: Allow users to write reviews and give star ratings
• Notifications: In-app notifications for invites, new books, etc.
• Mobile App: Native mobile applications for iOS and Android
• Public API: A public API for third-party integrations and extensions

• Performance: Database optimization and caching
• Scalability: PostgreSQL migration for larger deployments
• Testing: Comprehensive test suite
• Documentation: API documentation and user guides

This project is open source. See the LICENSE file for details.

• Issues: Report bugs and request features on GitHub
• Community: Join discussions on Bluesky
• Documentation: Check this README and inline code comments

Built with ❤️ using FastHTML and the AT-Proto ecosystem.