Collections & Bookmarks
Relevant source files
The following files were used as context for generating this wiki page:
The Collections and Bookmarks system provides a robust framework for organizing, tagging, and sharing code snippets within the CodeBot ecosystem. Collections allow users to group snippets manually or via "Smart" rules, while the Bookmark system (often integrated within collections as pinned items or specific line-level markers) enables granular navigation of code assets. The system is built on MongoDB, utilizing a repository pattern to separate database logic from the WebApp and Telegram bot interfaces.
Sources: webapp/README.md:58-86, database/collections_manager.py:9-15
System Architecture
The architecture follows a layered approach where the CollectionsManager serves as the core service layer, handling data validation, ACL checks, and MongoDB operations. The collections_api.py acts as the presentation layer for the WebApp, providing RESTful endpoints protected by authentication and rate limiting. The ProductionBackend in the MCP server also interfaces with the CollectionsManager to expose collection data to external agents.
Sources: webapp/collections_api.py:34-40, database/collections_manager.py:127-142, mcp_server/backend.py:129-138
Component Relationship Diagram
This diagram illustrates how different system components interact with the Collections database layer.
Data Models
User Collections
Collections are defined by the _CollectionDoc dataclass. They support different modes: manual, smart, or mixed. "Smart" collections populate items dynamically based on defined rules such as programming language or tags.
| Field | Type | Description |
|---|---|---|
user_id | Integer | The owner of the collection. |
name | String | Display name (max 80 chars). |
slug | String | URL-friendly identifier. |
mode | String | manual, smart, or mixed. |
is_active | Boolean | Soft-delete flag. |
is_archived | Boolean | Archive status for cleanup. |
folders | List | Embedded folder metadata (name, icon, order). |
Sources: database/collections_manager.py:112-124, database/collections_manager.py:169-178
Collection Items
Items are references to snippets (code_snippets) or large files (large_files). They store local metadata such as notes, custom tags, and folder placement.
Tagging System
The system implements a specific emoji-based tagging whitelist for collection items. Tags are categorized by priority, sentiment, security, and status.
| Category | Allowed Emojis | Metadata Examples |
|---|---|---|
| Priority | 🐢, 🔥 | Low priority, Urgent |
| Sentiment | 🔮, ♥️, 💎 | Magic, Favorite, Quality |
| Security | 🔐 | Secret |
| Status | 💭, ⏸️, 🎯 | Idea, Paused, Goal |
Sources: database/collections_manager.py:62-105
Functional Flows
Collection Sharing Flow
Users can enable sharing for a collection, which generates a secure token_urlsafe. This allows public access to a specific subset of collection metadata and files via a dedicated shared URL.
Folder Management
Collections support a flat folder structure (up to 20 folders per collection). Folders allow logical grouping within a collection. When a folder is deleted, items are moved back to the root (folder: "") rather than being deleted.
- Create Folder: Validates name length (max 60) and icon.
- Rename Folder: Updates the folder metadata in the collection doc and performs a
update_manyon thecollection_itemsto update theirfolderfield. - Delete Folder: Removes folder metadata and reconciles items by moving them to root or merging duplicates.
Sources: database/collections_manager.py:240-366
API Reference
The WebApp exposes several key endpoints for collection management. Authentication is required for all non-shared endpoints.
| Endpoint | Method | Action |
|---|---|---|
/api/collections | GET | List active collections (supports pagination). |
/api/collections/<id>/items | GET | Fetch items (supports folder filter). |
/api/collections/<id>/items | POST | Bulk add items to a collection. |
/api/collections/<id>/reorder | PUT | Update custom sort order for items. |
/api/collections/tags/metadata | GET | Fetch the tag whitelist and metadata. |
Sources: webapp/collections_api.py:126-140, webapp/collections_api.py:302-315, webapp/collections_api.py:616-620
Implementation Details
Data Integrity & Smart Projections
To maintain performance, the system follows the Smart Projection rule. List and search results for collection items never carry heavy fields like code or content. Full content is only retrieved during an explicit single-file fetch.
# database/collections_manager.py:633-636
manual_projection = {
"collection_id": 1,
"user_id": 1,
"source": 1,
"file_name": 1,
"folder": 1,
"note": 1,
"tags": 1,
"pinned": 1,
"custom_order": 1,
"workspace_state": 1,
"added_at": 1,
"updated_at": 1,
}
Sources: mcp_server/backend.py:13-18, database/collections_manager.py:633-646
Rate Limiting
Endpoints like update_item_tags are protected by a rate limiter to prevent abuse, allowing approximately 120 updates per minute per user/IP.
Sources: webapp/collections_api.py:91-118, webapp/collections_api.py:516-520
The Collections & Bookmarks system is a central pillar of the CodeBot organizational logic. By combining manual organization (Folders/Manual Collections) with automated grouping (Smart Collections) and granular metadata (Tags/Pins), it provides a scalable way to manage large repositories of code snippets. The architecture ensures that shared assets are handled securely while maintaining high performance through efficient database projections and caching strategies.