CONTRIBUTING.md

---

📖 Overview

This document describes how to work with the codebase as a developer.

💻 Development Environment

Tip

Follow these steps to set up your local development environment

🚀 Quick Setup Guide

1️⃣ Clone the repository

git clone https://github.com/AmaLS367/InvoiceFlowBot.git
cd InvoiceFlowBot

2️⃣ Create and activate virtual environment

python -m venv .venv
.\.venv\Scripts\Activate.ps1

3️⃣ Install dependencies in editable mode with dev extras

python -m pip install -e .[dev]

[!NOTE] This installs all development tools: pytest, ruff, mypy, pre-commit, bandit

🧪 Running Tests and Checks

Important

Always run these checks before committing code!

graph LR
    A[💻 Code Changes] -->|Run| B[🔍 Ruff Lint]
    B -->|Pass| C[🏷️ MyPy Types]
    C -->|Pass| D[🧪 Pytest]
    D -->|Pass| E[✅ Commit]

    style A fill:#4A90E2,stroke:#2c3e50,stroke-width:2px,color:#fff
    style B fill:#FFD93D,stroke:#2c3e50,stroke-width:2px,color:#333
    style C fill:#FF6B6B,stroke:#2c3e50,stroke-width:2px,color:#fff
    style D fill:#50C878,stroke:#2c3e50,stroke-width:2px,color:#fff
    style E fill:#B19CD9,stroke:#2c3e50,stroke-width:2px,color:#fff

Loading

⚡ Quick Check Commands

# 🔍 Lint check
python -m ruff check .

# 🏷️ Type check
python -m mypy backend/

# 🧪 Run tests
python -m pytest

Tool	Purpose	Config
🔍 ruff	Linting & formatting	pyproject.toml
🏷️ mypy	Type checking	pyproject.toml
🧪 pytest	Unit & integration tests	pyproject.toml
📊 coverage	Code coverage	pyproject.toml

Note

Unit tests and integration tests live under the tests/ package.

🎣 Pre-commit Hooks

This project uses pre-commit for automated local checks:

🔍 Ruff Lint & Format

🏷️ MyPy Type Checking

🔒 Bandit Security Checks

🔧 Install and run hooks

# Install hooks
pre-commit install

# Run on all files
pre-commit run --all-files

Note

CI will automatically run pre-commit on every push and pull request.

📜 Coding Guidelines

Important

Follow these principles to maintain code quality

🏗️ Architecture Principles

graph TD
    A[handlers] -->|uses| B[services]
    B -->|uses| C[domain]
    B -->|uses| D[ocr]
    B -->|uses| E[storage]
    F[core] -->|configures| A
    F -->|configures| B

    style A fill:#4A90E2,stroke:#2c3e50,stroke-width:2px,color:#fff
    style B fill:#50C878,stroke:#2c3e50,stroke-width:2px,color:#fff
    style C fill:#FFD93D,stroke:#2c3e50,stroke-width:2px,color:#333
    style D fill:#FF6B6B,stroke:#2c3e50,stroke-width:2px,color:#fff
    style E fill:#B19CD9,stroke:#2c3e50,stroke-width:2px,color:#fff
    style F fill:#A8E6CF,stroke:#2c3e50,stroke-width:2px,color:#333

Loading

✅ Best Practices

Rule	Description	Why
🐍 Python 3.11+	Target modern Python	New features & performance
🏛️ Layer Separation	domain → services → handlers	Clean architecture
🧠 Business Logic	Keep in services & domain	Not in handlers
⚡ Async I/O	For network & database	Better performance
🧪 Test Coverage	For non-trivial changes	Prevent regressions

📁 Project Structure

InvoiceFlowBot/
├── backend/
│   ├── 🎯 domain/      # Business entities
│   ├── ⚙️ services/    # Business logic
│   ├── 🔍 ocr/         # OCR providers
│   ├── 💾 storage/     # Database layer
│   ├── 🤖 handlers/    # Telegram handlers
│   └── 🔧 core/        # Configuration & DI

📚 Documentation

Tip

Keep documentation up-to-date with your changes!

🏗️ Architecture & Design

📊 Architecture Docs docs/en/architecture.md docs/ru/architecture.md High-level system diagrams and component interactions

📋 ADR (Architecture Decision Records) docs/adr/ Documented decisions for key technology choices

✍️ When to Update Docs

Change Type	Update
🔧 Configuration	docs/*/config.md
🐳 Deployment	docs/*/setup-*.md
🏗️ Architecture	docs/*/architecture.md
⚙️ Features	docs/*/usage.md

---

🤝 Thank You for Contributing!

Questions? Open an issue or discussion! 💬