docs: Add animated headers and badges to all documentation files

 Complete documentation overhaul for docs/en/ and docs/ru/:

 Animated Elements Added:
- Waving gradient headers for all docs pages
- Typing SVG animations with contextual messages
- Dynamic badges with for-the-badge style
- Technology-specific badges (pytest, SQLite, Alembic, Docker, etc.)
- Mermaid diagrams in overview.md for data flow visualization
- Interactive tables and collapsible sections
- Icon-based feature showcases

 Files Updated (26 total):

Russian docs (docs/ru/):
 index.md - Quick start cards + ADR list
 overview.md - Sequence diagram + detailed flow table
 architecture.md - Component diagram
 setup-local.md - Step badges
 setup-docker.md - Docker badges
 config.md - Environment variable badges
 database.md - SQLite + Alembic badges
 logging.md - Log files badges
 usage.md - Commands + workflow badges
 tests.md - pytest + coverage badges
 troubleshooting.md - Solutions badges
 development.md - Dev tools badges
 screenshots.md - Gallery badges

English docs (docs/en/):
 All corresponding files with matching styling

 Design Principles:
- Consistent color schemes across all pages
- Matching badges for related content
- Professional animated headers
- Easy navigation with anchor links
- GitHub-style callouts maintained

 Quality Checks Passed:
- Pre-commit hooks: all passed
- Formatting: consistent
- No linting errors

Author: AmaLS367

docs/en/architecture.md

@@ -1,8 +1,22 @@
-# Architecture
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=120&section=header&text=Architecture&fontSize=40&animation=fadeIn"/>
+
+<div align="center">
+
+<p align="center">
+  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=18&duration=3000&pause=1000&center=true&vCenter=true&width=500&lines=Clean+Architecture;Layered+Design;Modular+System" alt="Typing SVG" />
+</p>
+
+[![Architecture](https://img.shields.io/badge/Pattern-Clean%20Architecture-blue?style=for-the-badge)](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
+[![Layers](https://img.shields.io/badge/Layers-6-green?style=for-the-badge)](#layers)
+[![Mermaid](https://img.shields.io/badge/Diagrams-Mermaid-orange?style=for-the-badge)](#overall-component-diagram)
+
+</div>
+
+## 📋 About
 
 This document describes the high level architecture of InvoiceFlowBot.
 
-## Layers
+## 📦 Layers
 
 The project is split into several layers:
 

docs/en/config.md

@@ -1,4 +1,14 @@
-# ⚙️ Configuration
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=12,16,20&height=120&section=header&text=Configuration&fontSize=40&animation=fadeIn"/>
+
+<div align="center">
+
+[![dotenv](https://img.shields.io/badge/.env-Configuration-blue?style=for-the-badge)](https://github.com/theskumar/python-dotenv)
+[![pydantic](https://img.shields.io/badge/Pydantic-Settings-green?style=for-the-badge&logo=pydantic)](https://docs.pydantic.dev/)
+[![Variables](https://img.shields.io/badge/Env%20Vars-11-orange?style=for-the-badge)](#required-variables)
+
+</div>
+
+## 📋 About Configuration
 
 All settings live in environment variables. `config.py` loads `.env` with `os.getenv`, so updating the file and restarting the process is enough to apply changes.
 

docs/en/database.md

@@ -1,4 +1,14 @@
-# 🗄️ Database
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=120&section=header&text=Database&fontSize=40&animation=fadeIn"/>
+
+<div align="center">
+
+[![SQLite](https://img.shields.io/badge/Database-SQLite-blue?style=for-the-badge&logo=sqlite&logoColor=white)](https://www.sqlite.org/)
+[![Alembic](https://img.shields.io/badge/Migrations-Alembic-green?style=for-the-badge)](https://alembic.sqlalchemy.org/)
+[![WAL](https://img.shields.io/badge/Mode-WAL-orange?style=for-the-badge)](#schema)
+
+</div>
+
+## 📋 About Database
 
 InvoiceFlowBot relies on SQLite, a lightweight file-based database. By default data is stored in `data.sqlite` at the project root (or inside the container). Override the path with `INVOICE_DB_PATH` if needed.
 

docs/en/development.md

@@ -1,6 +1,14 @@
-# Development Guide
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=12,16,20&height=120&section=header&text=Development+Guide&fontSize=40&animation=fadeIn"/>
 
-## Database migrations
+<div align="center">
+
+[![Alembic](https://img.shields.io/badge/Migrations-Alembic-orange?style=for-the-badge)](https://alembic.sqlalchemy.org/)
+[![SQLite](https://img.shields.io/badge/Database-SQLite-blue?style=for-the-badge&logo=sqlite)](https://www.sqlite.org/)
+[![CI/CD](https://img.shields.io/badge/Pipeline-GitHub%20Actions-green?style=for-the-badge&logo=github)](https://github.com/features/actions)
+
+</div>
+
+## 🗄️ Database migrations
 
 The project uses Alembic to manage the SQLite schema.
 

docs/en/index.md

@@ -1,20 +1,75 @@
-# 📄 InvoiceFlowBot Documentation
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=150&section=header&text=Documentation&fontSize=50&animation=fadeIn&fontAlignY=38&desc=InvoiceFlowBot%20•%20Complete%20Guide&descAlignY=60&descSize=18"/>
+
+<div align="center">
+
+<p align="center">
+  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=18&duration=3000&pause=1000&center=true&vCenter=true&width=500&lines=Automated+Invoice+Processing;Telegram+%2B+OCR+%2B+SQLite;Complete+Project+Documentation" alt="Typing SVG" />
+</p>
+
+</div>
+
+## 📋 About
 
 InvoiceFlowBot is a Telegram assistant that automates invoice capture for finance teams. Users forward PDFs or photos, the bot extracts a structured draft via Mindee, lets the operator review and edit details, and persists confirmed invoices to SQLite.
 
-The workflow removes repetitive manual entry. Accountants receive a ready draft, adjust header fields or line items, add comments, and store the final version with a single command. Historical queries stay available in the same bot chat.
-
-## 📚 Documentation map
-
-- 📖 [System overview](overview.md) — architecture, components, and the data path from Telegram to the database
-- 🏗️ [Architecture](architecture.md) — high level architecture diagrams and component interactions
-- 💻 [Local setup](setup-local.md) — run without Docker, configure the virtual environment and `.env`
-- 🐳 [Docker setup](setup-docker.md) — container deployment, volume mounting, and upgrades
-- ⚙️ [Configuration](config.md) — every environment variable and how `config.py` reads it
-- 🗄️ [Database](database.md) — SQLite schema, entities, and backup tips
-- 📝 [Logging](logging.md) — log files, rotation, and recommended levels
-- 📖 [Usage](usage.md) — end-user flow, commands, and inline buttons
-- 🧪 [Tests](tests.md) — pytest instructions and coverage areas
-- 🔧 [Troubleshooting](troubleshooting.md) — quick fixes for common issues
-- 📸 [Screenshots](screenshots.md) — visual references for the most common bot flows
-- 📋 [Architecture decisions (ADR)](../adr/0001-mindee-as-primary-ocr-provider.md) — design decision records for key technology choices
+> [!NOTE]
+> The workflow removes repetitive manual entry. Accountants receive a ready draft, adjust header fields or line items, add comments, and store the final version with a single command.
+
+## 📚 Documentation Map
+
+<div align="center">
+
+### 🚀 Quick Start
+
+<table>
+<tr>
+<td width="50%" align="center">
+<img src="https://img.icons8.com/fluency/96/000000/laptop.png" width="64"/>
+<br/>
+<h4>💻 <a href="setup-local.md">Local Setup</a></h4>
+<sub>Python environment and dependencies</sub>
+</td>
+<td width="50%" align="center">
+<img src="https://img.icons8.com/fluency/96/000000/docker.png" width="64"/>
+<br/>
+<h4>🐳 <a href="setup-docker.md">Docker Setup</a></h4>
+<sub>Containerization and deployment</sub>
+</td>
+</tr>
+</table>
+
+### 📖 Main Documentation
+
+</div>
+
+| Section | Description |
+|---------|-------------|
+| 📖 [System Overview](overview.md) | Architecture, components, data flow |
+| 🏗️ [Architecture](architecture.md) | Diagrams and component interactions |
+| ⚙️ [Configuration](config.md) | Environment variables and settings |
+| 🗄️ [Database](database.md) | SQLite schema and migrations |
+| 📝 [Logging](logging.md) | Log files and levels |
+| 📖 [Usage](usage.md) | Commands and interactive buttons |
+| 🧪 [Tests](tests.md) | Pytest and code coverage |
+| 👨‍💻 [Development](development.md) | Developer guide |
+| 🔧 [Troubleshooting](troubleshooting.md) | Common issues and solutions |
+| 📸 [Screenshots](screenshots.md) | Visual examples |
+
+<details>
+<summary><b>📋 Architecture Decision Records (ADR)</b></summary>
+
+Documented decisions for key technologies:
+
+- [ADR-0001: Mindee as primary OCR provider](../adr/0001-mindee-as-primary-ocr-provider.md)
+- [ADR-0002: SQLite as primary storage](../adr/0002-sqlite-as-primary-storage.md)
+- [ADR-0003: Aiogram 3 as Telegram framework](../adr/0003-aiogram3-as-telegram-framework.md)
+
+</details>
+
+---
+
+<div align="center">
+
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&height=100&section=footer"/>
+
+</div>

docs/en/logging.md

@@ -1,4 +1,14 @@
-# 📝 Logging
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=12,16,20&height=120&section=header&text=Logging&fontSize=40&animation=fadeIn"/>
+
+<div align="center">
+
+[![Rotating](https://img.shields.io/badge/Handler-Rotating-blue?style=for-the-badge)](https://docs.python.org/3/library/logging.handlers.html)
+[![Files](https://img.shields.io/badge/Log%20Files-4-green?style=for-the-badge)](#log-files)
+[![Levels](https://img.shields.io/badge/Levels-Configurable-orange?style=for-the-badge)](#configuration-knobs)
+
+</div>
+
+## 📋 About Logging
 
 `ocr/engine/util.py` configures rotating log handlers the first time `get_logger` runs. By default logs live in `logs/` next to the source code or inside the directory specified via `LOG_DIR`.
 

docs/en/overview.md

@@ -1,4 +1,14 @@
-# 📖 System Overview
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=12,16,20&height=120&section=header&text=System+Overview&fontSize=40&animation=fadeIn"/>
+
+<div align="center">
+
+[![System](https://img.shields.io/badge/System-Architecture-blue?style=for-the-badge)](architecture.md)
+[![Components](https://img.shields.io/badge/Components-Modular-green?style=for-the-badge)](architecture.md)
+[![Flow](https://img.shields.io/badge/Data-Flow-orange?style=for-the-badge)](#data-flow)
+
+</div>
+
+## 📋 Description
 
 InvoiceFlowBot runs as a Telegram bot that receives documents from users and processes them through an OCR pipeline:
 

docs/en/screenshots.md

@@ -1,4 +1,17 @@
-# Bot screenshots
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=120&section=header&text=Screenshots&fontSize=40&animation=fadeIn"/>
+
+<div align="center">
+
+<p align="center">
+  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=18&duration=3000&pause=1000&center=true&vCenter=true&width=500&lines=Visual+Guide;Full+Workflow;From+Start+to+Save" alt="Typing SVG" />
+</p>
+
+![Gallery](https://img.shields.io/badge/Screenshots-4-blue?style=for-the-badge)
+![Status](https://img.shields.io/badge/Status-Updated-green?style=for-the-badge)
+
+</div>
+
+## 📖 About
 
 This gallery illustrates the full cycle: starting the chat, processing an invoice, editing data, and querying saved results.
 

docs/en/setup-docker.md

@@ -1,4 +1,14 @@
-# 🐳 Docker Setup
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=120&section=header&text=Docker+Setup&fontSize=40&animation=fadeIn"/>
+
+<div align="center">
+
+[![Docker](https://img.shields.io/badge/Docker-Compose-blue?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/)
+[![Container](https://img.shields.io/badge/Container-Ready-green?style=for-the-badge)](https://hub.docker.com/)
+[![Quick Start](https://img.shields.io/badge/Setup-5%20Minutes-orange?style=for-the-badge)](#start-the-stack)
+
+</div>
+
+## 📋 About Docker
 
 Docker provides a self-contained runtime for InvoiceFlowBot: Python, dependencies, and the bot code run inside the container, while the host only keeps the database and logs.
 

docs/en/setup-local.md

@@ -1,4 +1,14 @@
-# 💻 Local Setup
+<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=12,16,20&height=120&section=header&text=Local+Setup&fontSize=40&animation=fadeIn"/>
+
+<div align="center">
+
+[![Python](https://img.shields.io/badge/Python-3.11+-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
+[![venv](https://img.shields.io/badge/Environment-Virtual-green?style=for-the-badge)](https://docs.python.org/3/library/venv.html)
+[![Setup](https://img.shields.io/badge/Guide-Step%20by%20Step-orange?style=for-the-badge)](#steps)
+
+</div>
+
+## 📋 About
 
 > [!NOTE]
 > This guide is for installation without Docker. For quick start, see [Docker setup](setup-docker.md).