Contributing Guidelines & AI Directives

Relevant source files

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

• CLOUD.md
• tests/conftest.py
• FEATURE_SUGGESTIONS/IMPROVEMENT_SUGGESTIONS.md
• code_review_2025_10/REFACTORING_PLAN.md
• PROMPTS_WEBAPP_LAYERING.md

This document outlines the development standards, architectural directives, and operational constraints for contributors and AI assistants working on the CodeBot repository. It focuses on maintaining a layered architecture, improving code quality through modularity, and ensuring secure, testable deployments.

Introduction

The CodeBot project is a sophisticated Telegram bot and WebApp system designed for managing code snippets. To maintain the project's integrity, all contributions must adhere to a strict layered architecture that separates concerns between presentation, application logic, and infrastructure. Contributors are expected to follow specific git conventions and development rules to ensure stability across local and cloud environments.

AI Assistant Directives (Project Rules)

When AI tools or automated agents interact with the repository, they must follow a set of "AI Quickstart" rules to prevent environment corruption and maintain security.

Operational Constraints

The following restrictions apply to all automated agents:

• No Sudo: Escalated privileges are strictly prohibited.
• No Long-lived Processes: Do not start background services or watch commands.
• Non-interactive Commands: Avoid interactive sessions (e.g., git rebase -i, nano, git add -i).
• Config Integrity: Do not alter global git configurations.
• Remote Push: Pushing to remote repositories is forbidden unless explicitly requested.

Mandatory Practices

• Tooling: Use approved file tools (Read/LS/Grep/Glob) rather than generic shell commands like cat or find.
• Paths: Always use absolute paths for file references.
• I/O Safety: Perform all script or test I/O operations exclusively under the /tmp directory.
• Style Consistency: Keep edits minimal and strictly follow the existing code style.

Sources: CLOUD.md:6-21

Layered Architecture Standards

The project is moving toward a strict four-layer architecture to eliminate "God Object" anti-patterns and mixed concerns.

Architectural Layers

Layer	Responsibility	Components
Presentation (Web/Bot)	User interface and request handling	Routes, request/response schemas (Pydantic), view models, templates.
Application	Use-case orchestration	Service classes (e.g., SnippetService), DTOs.
Domain	Pure business logic	Entities, value objects, validators (e.g., LanguageDetector).
Infrastructure	External interactions	Repositories, database managers, third-party API clients.

Sources: PROMPTS_WEBAPP_LAYERING.md:65-73

Layer Interaction Flow

The following sequence illustrates a standard request flow adhering to these boundaries:

Code Quality and Refactoring

Large files (e.g., main.py exceeding 2,000 lines) are currently flagged for refactoring. Contributors should follow the modularization plan to break these into specialized modules.

Refactoring Directives

• Function Responsibility: Functions should do one thing and have one level of abstraction.
• Module Splitting: Move lock management to core/lock_manager.py, middleware to core/middleware.py, and commands to handlers/commands.py.
• Type Hinting: New code must include complete type hints. Use mypy in strict mode for validation.
• Logging: Replace all print() statements with structured logging using logger.info() or logger.error().

Sources: FEATURE_SUGGESTIONS/IMPROVEMENT_SUGGESTIONS.md:21-42, code_review_2025_10/REFACTORING_PLAN.md:20-56

Testing and Deployment

Testing Requirements

The project uses pytest and targets an 85% code coverage rate.

• Safety: Use the tmp_path fixture for any file I/O within tests.
• Environment: Disable activity reporting and real database connections for unit tests using DISABLE_ACTIVITY_REPORTER=1 and DISABLE_DB=1.
• Performance: Performance-intensive tests should be marked and run specifically using pytest -m performance.

Sources: CLOUD.md:60-75, FEATURE_SUGGESTIONS/IMPROVEMENT_SUGGESTIONS.md:118-125

Git Commit Conventions

All commits must follow the Conventional Commits specification:

• Types: feat | fix | docs | test | refactor | chore | perf.
• Format: Prefer heredoc messages for multi-line explanations.

git commit -m "$(cat <<'EOF'
feat: add automated syntax detection

- Integrates Pygments for 100+ languages
- Implements fallback for unknown extensions
EOF
)"

Sources: CLOUD.md:81-91

Summary

Contributors must adhere to the layered architectural boundaries, prioritize structured logging over print statements, and maintain high test coverage. AI assistants are constrained to non-interactive, safe file operations within /tmp. Adherence to these guidelines ensures CodeBot remains a production-grade, secure, and maintainable platform.