Web Application Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• PROMPTS_WEBAPP_LAYERING.md
• webapp/README.md
• GUIDES/ARCHITECTURE.md
• webapp/app.py
• create_webapp.sh
• CLOUD.md

The Web Application Architecture of CodeBot is designed to provide a comprehensive web interface for managing and viewing code snippets saved via the Telegram bot. Built using the Flask framework, it serves as a bridge between the user and the underlying MongoDB storage, offering advanced search, visualization (Markdown, SVG, HTML), and management features such as collections and bookmarks.

The architecture is currently undergoing a transition from a monolithic route-heavy structure to a modern layered architecture. This shift aims to decouple business logic from HTTP handling by leveraging shared domain entities and infrastructure facades already established in the core project.

Sources: webapp/README.md, PROMPTS_WEBAPP_LAYERING.md

Layered Architectural Overview

The target architecture for the web application follows a four-layer pattern to ensure maintainability and consistency with the Telegram bot component.

Architectural Layers

Layer	Responsibility	Key Components
Presentation	Handles HTTP requests, input validation (Pydantic), and rendering.	Flask Routes, Jinja2 Templates, View Models
Application	Orchestrates use cases and business flows using DTOs.	SnippetService, Shared Services
Domain	Pure business logic, entities, and validation rules.	Snippet Entity, LanguageDetector, CodeNormalizer
Infrastructure	Concrete implementations for persistence and external APIs.	FilesFacade, MongoDB Repositories

Sources: PROMPTS_WEBAPP_LAYERING.md

Data Flow Diagram

The following diagram illustrates the request flow from the User Interface through the architectural layers to the database.

This diagram shows the standard flow where a route delegates logic to a Service, which interacts with the FilesFacade to access MongoDB.
Sources: PROMPTS_WEBAPP_LAYERING.md, webapp/README.md

Core Components and Modules

Application Entry Point

The application is initialized in webapp/app.py, which serves as the main Flask entry point. It includes essential health check endpoints and serves as the mounting point for various specialized API blueprints.

# webapp/app.py:5-12
@app.route('/health')
def health():
    return jsonify({'status': 'healthy'})

Sources: webapp/app.py:5-12, create_webapp.sh

Specialized API Modules

The web application is decomposed into several feature-specific modules:

• Bookmarks API: Manages user-specific line bookmarks and favorites within files.
• Collections API: Handles the grouping of files into manual or "smart" collections.
• Sticky Notes API: Provides functionality for Markdown-based interactive notes anchored to specific code lines.
• Search Engine: Implements Global, Regex, Fuzzy, and Full-Text search capabilities.

Sources: webapp/README.md

Deployment and Infrastructure

Environment Configuration

The web application requires specific environment variables for operation, particularly for database connectivity and Telegram authentication integration.

Variable	Description	Requirement
SECRET_KEY	Flask session encryption key	Required
MONGODB_URL	Connection string for MongoDB	Required
BOT_TOKEN	Telegram Bot API token	Required
WEBAPP_URL	Public URL for the deployed web app	Recommended
ASSET_VERSION	Dynamic versioning for cache busting	Auto-generated

Sources: webapp/README.md, CLOUD.md

Production Pipeline

The application uses a specialized startup script (scripts/start_webapp.sh) that performs critical pre-flight tasks:

1. Cache Busting: Generates a dynamic ASSET_VERSION based on Git commits.
2. Warmup: Executes a best-effort curl to /healthz to warm up MongoDB connections and indexes before the deployment is marked as active.

Sources: webapp/README.md

System Integration

The web application integrates with several external services and core project modules as shown in the system architecture.

This diagram represents the high-level relationship between the Web Application, shared core analyzer services, and the persistence layer.
Sources: GUIDES/ARCHITECTURE.md, webapp/README.md

Security and Authentication

Authentication is primarily handled through the Telegram Login Widget or a one-time token generated by the bot. The system supports session persistence (30 days) and role-based access control (Regular, Premium, Admin).

Sources: webapp/README.md

Conclusion

The Web Application Architecture of CodeBot provides a robust, visual interface for code management while maintaining strict separation between the presentation layer and core business logic. By utilizing a shared infrastructure layer (FilesFacade) and domain logic (CodeNormalizer), it ensures that features like code detection and storage remain consistent across both the Telegram bot and the web interface.