Database Schema & Models
Relevant source files
The following files were used as context for generating this wiki page:
The CodeBot project utilizes a MongoDB-based storage layer to manage code snippets, user metadata, and system metrics. The persistence architecture is built around a Repository pattern that abstracts complex MongoDB operations into a clean API for the bot and web applications. The system supports advanced features such as version control for code snippets, soft-deletion via a recycle bin mechanism, and high-performance querying through specialized indexing strategies.
The database is managed by the DatabaseManager, which handles connection pooling, background reconnection logic, and automated index creation. Data is organized into several key collections, including code_snippets for primary storage, users for preferences and tokens, and specialized collections for community snippets and performance metrics.
Sources: database/manager.py, database/repository.py, GUIDES/ARCHITECTURE.md
Core Data Entities
The system defines several primary entities that represent the core domain of the application. These entities are stored as BSON documents in MongoDB and are represented in the codebase via classes and dataclasses.
Code Snippets
The CodeSnippet entity is the central unit of storage. It represents a specific version of a code file owned by a user. To support version history, every edit creates a new document with an incremented version number while maintaining the same file_name.
The diagram above illustrates the typical schema for a code snippet document.
Sources: database/repository.py:141-180, database/manager.py:534-543
User Metadata and Preferences
The users collection stores account-level information, including integration tokens for external services like GitHub and Google Drive. It also tracks UI preferences such as image generation settings and welcome modal status.
| Field | Type | Description |
|---|---|---|
user_id | int | Primary unique identifier (Telegram ID) |
username | string | Optional Telegram handle |
github_token | string | Encrypted OAuth token for GitHub integration |
drive_tokens | dict | Encrypted Google Drive credentials |
selected_repo | string | Currently active GitHub repository for sync |
is_blocked | bool | Administrative flag to restrict access |
Sources: database/repository.py:1000-1150, database/manager.py:750-760
Database Architecture and Connectivity
The persistence layer is designed for high availability and performance. It includes a DatabaseManager that implements a singleton-like lifecycle to prevent accidental re-creation of connection pools.
Connection Lifecycle
The manager supports graceful degradation. If MongoDB is unavailable during startup, the system enters a "NoOp" mode, allowing the application to boot while a background thread attempts to establish a connection using exponential backoff.
The diagram shows the logic flow for database connectivity and the fallback mechanism.
Sources: database/manager.py:445-530
Repository and Storage Operations
The Repository class provides a high-level API for data manipulation. It handles logic such as automatic code normalization before saving and cache invalidation.
Versioning Logic
When a file is saved, the repository fetches the current latest version to determine the next version number. It also preserves metadata like "favorite" status and "tags" across versions unless explicitly changed.
Performance Optimizations (Smart Projection)
To reduce memory footprint and network latency, list and search operations use "Smart Projections." Heavy fields like code and content are excluded from results by default, being fetched only when a specific file is requested by its unique ID or name.
Sources: database/repository.py:44-55, database/repository.py:141-170, mcp_server/backend.py:20-40
Indexing Strategy
Specialized indexes are maintained to ensure that frequent operations like dashboard loading, text searching, and background job processing remain performant.
| Collection | Index Name | Keys | Purpose |
|---|---|---|---|
code_snippets | idx_snippets_latest_version | user_id, is_active, file_name, version | Optimized retrieval of latest file versions |
code_snippets | search_text_idx | file_name (text), description (text), code (text) | Full-text search support |
note_reminders | push_polling_optimized_idx | remind_at, status | Polling for pending notifications |
job_runs | idx_job_runs_id | run_id | Fast status updates for background jobs |
Sources: database/manager.py:650-850
Specialized Collections
Beyond snippets and users, the system manages several ancillary data structures:
- Snippet Library: A public catalog of curated or community-submitted code snippets. Documents include a
statusfield for an approval workflow (pending,approved,rejected). - Sticky Notes: Visual annotations attached to code files. These use a
scope_idderived from the user and file name to maintain associations even across renames. - Recycle Bin: Instead of physical deletion, snippets are marked
is_active: Falseand assigned adeleted_expires_attimestamp for automated cleanup after a TTL period.
Sources: services/snippet_library_service.py:140-200, database/repository.py:850-920, mcp_server/backend.py:270-320
Summary
The CodeBot database schema is a document-oriented model optimized for versioned code storage and high-concurrency bot interactions. By utilizing a robust Repository layer and comprehensive indexing, the system maintains high performance even as user data grows. The inclusion of background reconnection logic and NoOp fallbacks ensures that the application remains resilient to transient database outages.