{"id":30782298,"url":"https://github.com/andreasthinks/bibliome","last_synced_at":"2025-10-22T03:08:33.397Z","repository":{"id":309582303,"uuid":"1036794149","full_name":"AndreasThinks/bibliome","owner":"AndreasThinks","description":"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.","archived":false,"fork":false,"pushed_at":"2025-08-26T20:24:22.000Z","size":2382,"stargazers_count":5,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-27T02:19:28.297Z","etag":null,"topics":["books","bookshelf","fasthtml","python","web"],"latest_commit_sha":null,"homepage":"https://bibliome.club/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AndreasThinks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-12T15:37:11.000Z","updated_at":"2025-08-25T20:04:04.000Z","dependencies_parsed_at":"2025-08-13T17:48:02.071Z","dependency_job_id":null,"html_url":"https://github.com/AndreasThinks/bibliome","commit_stats":null,"previous_names":["andreasthinks/bibliome"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AndreasThinks/bibliome","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndreasThinks%2Fbibliome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndreasThinks%2Fbibliome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndreasThinks%2Fbibliome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndreasThinks%2Fbibliome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AndreasThinks","download_url":"https://codeload.github.com/AndreasThinks/bibliome/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndreasThinks%2Fbibliome/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273739846,"owners_count":25159429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["books","bookshelf","fasthtml","python","web"],"created_at":"2025-09-05T09:36:55.486Z","updated_at":"2025-10-22T03:08:33.315Z","avatar_url":"https://github.com/AndreasThinks.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bibliome - Collaborative Bookshelf Platform\n\nA 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.\n\n## 🚀 Features\n\n### ✅ Implemented Features\n\n#### Core Functionality\n- **Bookshelf Creation \u0026 Management**: Create named bookshelves with unique URLs\n- **Advanced Search**: Search shelves by name, description, and contained books (title, author, ISBN)\n- **Book Search \u0026 Addition**: Integrated Google Books API for rich book metadata\n- **Upvoting System**: Community-driven book curation through upvotes\n- **Privacy Controls**: Public, Link-only, and Private bookshelf options\n- **Role-Based Permissions**: Owner, Admin, Editor, and Viewer roles\n\n#### Discovery \u0026 Social\n- **Network Activity Feed**: See recent activity from users you follow on Bluesky\n- **Explore Page**: Browse all public bookshelves in the community\n- **Community Reading Section**: Discover recently added books from public shelves\n\n#### Authentication \u0026 User Management\n- **Bluesky Authentication**: Secure login via AT-Proto\n- **User Profiles**: Display names, handles, and avatars from Bluesky\n- **Session Management**: Persistent login sessions\n\n#### Sharing \u0026 Collaboration\n- **Invite System**: Generate invite links with role assignments and expiration\n- **Member Management**: Add, remove, and manage member permissions\n- **Privacy Settings**: Dynamic privacy level changes\n\n#### User Interface\n- **Responsive Design**: Mobile-friendly interface with PicoCSS\n- **Interactive Book Cards**: Clickable books linking to Google Books\n- **Real-time Search**: HTMX-powered book search with instant results\n- **Unified Management**: Combined edit, share, and delete interface\n- **Delete Confirmation**: Type-to-confirm deletion for safety\n\n#### Recent Improvements\n- **Advanced Search**: Implemented hybrid search for shelves and books (title, author, ISBN)\n- **Network Activity Feed**: Added a social feed based on Bluesky connections\n- **Community Discovery**: New \"Explore\" page and community reading sections\n- **Enhanced Navigation**: Integrated search and discovery into the main navigation\n- **Improved UI/UX**: Redesigned search page, better empty states, and clearer titles\n- **Fixed Table Name Bug**: Resolved database query errors in search\n\n## 🛠️ Tech Stack\n\n- **Backend \u0026 Frontend**: FastHTML\n- **Authentication**: AT-Proto (Bluesky)\n- **Database**: SQLite with FastLite + FastMigrate\n- **APIs**: Google Books API\n- **Styling**: PicoCSS + Custom CSS\n- **JavaScript**: HTMX for dynamic interactions\n\n## 🗄️ Database Migrations\n\nBibliome uses **fastmigrate** for database schema management, providing version control for your database structure and safe schema evolution.\n\n### How It Works\n\nFastMigrate follows the standard database migration pattern:\n- **Migration scripts** define database versions (e.g., `0001-initialize.sql`, `0002-add-feature.sql`)\n- **Automatic application** of pending migrations on startup\n- **Version tracking** ensures each migration runs exactly once\n- **Safe evolution** from any previous version to the latest\n\n### Migration Files\n\nMigration scripts are stored in the `migrations/` directory:\n\n```\nmigrations/\n└── 0001-initialize.sql    # Initial database schema\n```\n\nEach migration file:\n- **Must be numbered sequentially** (0001, 0002, 0003, etc.)\n- **Should have a descriptive name** after the number\n- **Contains SQL statements** to modify the database\n- **Runs exactly once** when the application starts\n\n### Current Schema (Version 1)\n\nThe initial migration (`0001-initialize.sql`) creates all necessary tables:\n- `user` - Bluesky user profiles and authentication data\n- `bookshelf` - Book collections with privacy and metadata  \n- `book` - Individual books with metadata from Google Books API\n- `permission` - Role-based access control for bookshelves\n- `bookshelf_invite` - Invitation system for sharing\n- `upvote` - User votes on books for curation\n- `activity` - Tracks user actions for the social feed\n\n### Adding New Migrations\n\nWhen you need to modify the database schema:\n\n1. **Create a new migration file** in the `migrations/` directory:\n   ```bash\n   # Example: Adding a new column to the book table\n   touch migrations/0002-add-book-rating.sql\n   ```\n\n2. **Write the SQL changes**:\n   ```sql\n   -- migrations/0002-add-book-rating.sql\n   -- Add rating column to books table\n   \n   ALTER TABLE book ADD COLUMN rating INTEGER DEFAULT 0;\n   CREATE INDEX idx_book_rating ON book(rating);\n   ```\n\n3. **Test the migration**:\n   ```bash\n   # The migration will run automatically when you start the app\n   python app.py\n   ```\n\n4. **Verify the changes**:\n   ```bash\n   # Check current database version\n   python -c \"from fastmigrate.core import get_db_version; print(f'Database version: {get_db_version(\\\"data/bookdit.db\\\")}')\"\n   ```\n\n### Migration Best Practices\n\n#### ✅ Do's\n- **Always backup** your database before running migrations in production\n- **Test migrations** on a copy of production data first\n- **Use descriptive names** for migration files\n- **Keep migrations small** and focused on one change\n- **Add indexes** for new columns that will be queried\n- **Use transactions** for complex multi-step migrations\n\n#### ❌ Don'ts\n- **Never modify existing migration files** once they've been applied\n- **Don't skip version numbers** (use sequential numbering)\n- **Avoid destructive operations** without careful consideration\n- **Don't mix schema and data changes** in the same migration\n\n### CLI Commands\n\nFastMigrate provides command-line tools for database management:\n\n```bash\n# Check current database version\nfastmigrate_check_version --db data/bookdit.db\n\n# Create a new managed database (if needed)\nfastmigrate_create_db --db data/bookdit.db\n\n# Run pending migrations manually\nfastmigrate_run_migrations --db data/bookdit.db --migrations migrations/\n\n# Check what migrations would run\nls migrations/ | sort\n```\n\n### Example Migration Scenarios\n\n#### Adding a New Feature\n```sql\n-- migrations/0002-add-book-reviews.sql\n-- Add book reviews functionality\n\nCREATE TABLE book_review (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    book_id INTEGER NOT NULL,\n    user_did TEXT NOT NULL,\n    rating INTEGER NOT NULL CHECK (rating \u003e= 1 AND rating \u003c= 5),\n    review_text TEXT DEFAULT '',\n    created_at DATETIME,\n    updated_at DATETIME,\n    FOREIGN KEY (book_id) REFERENCES book(id),\n    FOREIGN KEY (user_did) REFERENCES user(did)\n);\n\nCREATE INDEX idx_book_review_book ON book_review(book_id);\nCREATE INDEX idx_book_review_user ON book_review(user_did);\nCREATE INDEX idx_book_review_rating ON book_review(rating);\n```\n\n#### Modifying Existing Data\n```sql\n-- migrations/0003-normalize-book-authors.sql\n-- Split author field into separate authors table\n\nCREATE TABLE book_author (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    book_id INTEGER NOT NULL,\n    author_name TEXT NOT NULL,\n    author_order INTEGER DEFAULT 1,\n    FOREIGN KEY (book_id) REFERENCES book(id)\n);\n\n-- Migrate existing author data\nINSERT INTO book_author (book_id, author_name, author_order)\nSELECT id, author, 1 \nFROM book \nWHERE author IS NOT NULL AND author != '';\n\nCREATE INDEX idx_book_author_book ON book_author(book_id);\nCREATE INDEX idx_book_author_name ON book_author(author_name);\n```\n\n### Troubleshooting Migrations\n\n#### Migration Failed\nIf a migration fails:\n1. **Check the error message** in the application logs\n2. **Fix the SQL syntax** in the migration file\n3. **Restore from backup** if the database is corrupted\n4. **Test the fixed migration** on a copy first\n\n#### Database Version Mismatch\nIf you see version-related errors:\n```bash\n# Check current version\nfastmigrate_check_version --db data/bookdit.db\n\n# List available migrations\nls -la migrations/\n\n# Manually run migrations if needed\nfastmigrate_run_migrations --db data/bookdit.db --migrations migrations/\n```\n\n#### Rolling Back Changes\nFastMigrate doesn't support automatic rollbacks, but you can:\n1. **Create a new migration** that reverses the changes\n2. **Restore from a backup** taken before the migration\n3. **Manually fix** the database if the change was small\n\n### Production Deployment\n\nFor production deployments:\n\n1. **Backup the database** before deploying:\n   ```bash\n   cp data/bookdit.db data/bookdit.db.backup.$(date +%Y%m%d_%H%M%S)\n   ```\n\n2. **Test migrations** on a copy of production data first\n\n3. **Deploy with automatic migrations**:\n   - Migrations run automatically when the application starts\n   - Monitor logs for migration success/failure\n   - Have a rollback plan ready\n\n4. **Verify the deployment**:\n   ```bash\n   # Check database version after deployment\n   fastmigrate_check_version --db data/bookdit.db\n   ```\n\n## 📋 Setup Instructions\n\n### Prerequisites\n- Python 3.8+\n- A Google Books API key\n- A Bluesky account for testing\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd Bibliome\n   ```\n\n2. **Install dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Configure environment variables**\n   ```bash\n   cp .env.example .env\n   ```\n   \n   Edit `.env` and add your configuration:\n   ```env\n   # Bluesky/AT-Proto Configuration\n   BLUESKY_HANDLE=your-handle.bsky.social\n   BLUESKY_PASSWORD=your-app-password\n\n   # Google Books API\n   GOOGLE_BOOKS_API_KEY=your-google-books-api-key\n\n   # Application Settings\n   SECRET_KEY=your-secret-key-here\n   DEBUG=true\n   HOST=localhost\n   PORT=5001\n   BASE_URL=http://0.0.0.0:5001/\n   ```\n\n4. **Run the application**\n   ```bash\n   python app.py\n   ```\n\n5. **Access the application**\n   Open your browser to `http://localhost:5001`\n\n### Getting API Keys\n\n#### Google Books API Key\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project or select an existing one\n3. Enable the Books API\n4. Create credentials (API Key)\n5. Add the API key to your `.env` file\n\n#### Bluesky App Password\n1. Log into Bluesky\n2. Go to Settings → Privacy and Security → App Passwords\n3. Generate a new app password\n4. Use your handle and app password in the `.env` file\n\n## 🎯 Usage Guide\n\n### Creating Your First Bookshelf\n\n1. **Login** with your Bluesky account\n2. **Click \"Create New Shelf\"** on the homepage\n3. **Fill in details**:\n   - Name: Give your bookshelf a descriptive name\n   - Description: Optional description of what the shelf is about\n   - Privacy: Choose who can see your shelf\n4. **Click \"Create Bookshelf\"**\n\n### Adding Books\n\n1. **Navigate to your bookshelf**\n2. **Use the search box** to find books by title, author, or ISBN\n3. **Click \"Add to Shelf\"** on any search result\n4. **Books appear immediately** in your collection\n\n### Discovering Bookshelves\n\n- **Explore Page**: Click \"Explore\" in the navigation to browse all public bookshelves.\n- **Search Page**: Click \"Search\" to find specific shelves.\n  - Use the main search bar to search by shelf name, description, or contained books.\n  - Click \"Advanced Search\" to filter by specific book titles, authors, or ISBNs.\n- **Network Feed**: On your dashboard, see shelves recently created or added to by people you follow on Bluesky.\n\n### Managing Your Bookshelf\n\n1. **Click \"Manage\"** on any bookshelf you own or have admin access to\n2. **Edit Details**: Change name, description, or privacy settings\n3. **Share \u0026 Members**: \n   - Generate invite links with specific roles\n   - Manage existing members and their permissions\n   - View pending invitations\n4. **Delete Shelf** (owners only): Permanently delete with confirmation\n\n### Collaboration Features\n\n#### Inviting Others\n1. Go to the **Manage** page of your bookshelf\n2. In the **Share \u0026 Members** section, set:\n   - Role for new members (Viewer, Editor, Admin)\n   - Expiration time (optional)\n   - Maximum uses (optional)\n3. **Generate Invite Link** and share it\n\n#### Role Permissions\n- **Owner**: Full control, can delete shelf\n- **Admin**: Manage members, edit shelf, add books\n- **Editor**: Add books and upvote\n- **Viewer**: View books only\n\n### Privacy Levels\n\n- **Public**: Anyone can find and view your bookshelf\n- **Link-only**: Only people with the direct link can view\n- **Private**: Only invited members can view\n\n## 🏗️ Architecture\n\n### Database Models\n- **User**: Bluesky user profiles and authentication data\n- **Bookshelf**: Book collections with privacy and metadata\n- **Book**: Individual books with metadata from Google Books API\n- **Permission**: Role-based access control for bookshelves\n- **BookshelfInvite**: Invitation system for sharing\n- **Upvote**: User votes on books for curation\n- **Activity**: Tracks user actions for the social feed\n\n### Key Components\n- **Authentication** (`auth.py`): Bluesky AT-Proto integration\n- **API Clients** (`api_clients.py`): Google Books API wrapper\n- **Models** (`models.py`): Database models and business logic\n- **Components** (`components.py`): Reusable UI components\n- **Main App** (`app.py`): FastHTML routes and application logic\n\n## 🔧 Development\n\n### Project Structure\n```\nBibliome/\n├── app.py              # Main application\n├── auth.py             # Authentication logic\n├── api_clients.py      # External API integrations\n├── models.py           # Database models\n├── components.py       # UI components\n├── requirements.txt    # Python dependencies\n├── .env.example        # Environment template\n├── static/\n│   └── css/\n│       └── styles.css  # Custom styling\n└── data/               # SQLite database storage\n```\n\n### Running Tests\n```bash\npython test_basic.py\n```\n\n### Contributing\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n#### Google Books API Not Working\n- Verify your API key is correct in `.env`\n- Check that the Books API is enabled in Google Cloud Console\n- Ensure you haven't exceeded API quotas\n\n#### Books Not Appearing in Search\n- Check the console for API errors\n- Verify your internet connection\n- Try different search terms (title, author, ISBN)\n\n#### Invite Links Not Working\n- Ensure `BASE_URL` is set correctly in `.env`\n- Check that the invite hasn't expired or reached max uses\n- Verify the bookshelf privacy settings\n\n#### Authentication Issues\n- Verify your Bluesky handle and app password\n- Check that you're using an app password, not your main password\n- Ensure the Bluesky service is accessible\n\n## 🚀 Deployment\n\n### Environment Variables for Production\n```env\nDEBUG=false\nHOST=0.0.0.0\nPORT=5001\nBASE_URL=https://yourdomain.com/\nSECRET_KEY=your-production-secret-key\n```\n\n### Security Considerations\n- Use a strong, unique `SECRET_KEY` in production\n- Enable HTTPS for production deployments\n- Regularly rotate API keys\n- Monitor for unusual activity\n\n## 📈 Future Enhancements\n\n### Planned Features\n- **Export/Import**: Backup and restore bookshelves\n- **Enhanced Search**: Filter by genre, publication date, etc.\n- **Reading Lists**: Track reading progress and status (e.g., \"To Read\", \"Reading\", \"Read\")\n- **Book Reviews \u0026 Ratings**: Allow users to write reviews and give star ratings\n- **Notifications**: In-app notifications for invites, new books, etc.\n- **Mobile App**: Native mobile applications for iOS and Android\n- **Public API**: A public API for third-party integrations and extensions\n\n### Technical Improvements\n- **Performance**: Database optimization and caching\n- **Scalability**: PostgreSQL migration for larger deployments\n- **Testing**: Comprehensive test suite\n- **Documentation**: API documentation and user guides\n\n## 📄 License\n\nThis project is open source. See the LICENSE file for details.\n\n## 🤝 Support\n\n- **Issues**: Report bugs and request features on GitHub\n- **Community**: Join discussions on Bluesky\n- **Documentation**: Check this README and inline code comments\n\n---\n\nBuilt with ❤️ using FastHTML and the AT-Proto ecosystem.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreasthinks%2Fbibliome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandreasthinks%2Fbibliome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreasthinks%2Fbibliome/lists"}