docs: setup MkDocs documentation with GitHub Actions automation (#102)

* docs: setup MkDocs documentation with GitHub Actions automation

* docs: update

* docs: update

* docs: update

Author: sannarat

.github/workflows/deploy-docs.yml

@@ -0,0 +1,26 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main  # Замени на master, если у тебя главная ветка называется master
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Configure Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          
+      - name: Install dependencies
+        run: pip install mkdocs-material
+        
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

docs/app/ui.md

@@ -0,0 +1,87 @@
+# Архитектура UI-слоя (Presentation Layer)
+
+Презентационный слой приложения разработан на базе **Jetpack Compose** и реализует реактивный подход к отображению данных. Управление состоянием разделено на два подхода в зависимости от специфики экрана: использование классического `StateFlow` (для авторизации и онбординга) и прямое использование `mutableStateOf` во ViewModel для минимизации оверхеда при частых обновлениях (списки заметок, редактор).
+
+---
+
+## 1. Компоненты UI-слоя
+
+Вся бизнес-логика презентации инкапсулирована во ViewModels, которые внедряются в UI-компоненты с помощью DI-фреймворка **Koin**.
+
+| ViewModel | Тип состояния | Стратегия навигации | Архитектурная роль |
+| :--- | :--- | :--- | :--- |
+| `AuthViewModel` | `StateFlow<AuthUiState>` | Шаги внутри экрана (`AuthScreenStep`) | Управление сессией пользователя (Firebase Auth / Google Sign-In), валидация и обработка ошибок входа. |
+| `OnboardingViewModel` | `MutableStateFlow` / `StateFlow` | Пошаговый интерактивный тур | Подсчет координат целевых элементов (`Rect`), управление подсказками и сохранение флага завершения в `Preferences`. |
+| `NotesViewModel` | `mutableStateOf(NotesUiState)` | Стейт-ориентированная (`NotesUiScreen`) | Главный координатор списков: папки, заметки, поиск, избранное. Управляет навигацией через изменение поля `screen`. |
+| `EditorViewModel` | Раздельные `mutableStateOf` поля | Назад (BackHandler) | Облегченная модель для изоляции состояния конкретной редактируемой заметки (динамический ввод текста, вложения). |
+
+---
+
+## 2. Схемы управления состоянием и навигации
+
+### Стейт-ориентированная навигация в списках (`NotesViewModel`)
+
+В отличие от классического Jetpack Compose Navigation, переключение между экраном папок (`Directories`) и экраном заметок конкретной папки (`Notes`) происходит декларативно через изменение свойства `uiState.screen` типа `NotesUiScreen`. Это позволяет сохранять контекст данных без сложной передачи аргументов по строковым путям.
+
+```mermaid
+graph LR
+    A[DirectoriesScreen] -- Выбор папки / Клик --> B(NotesViewModel.onDirectoryClick)
+    B --> C[Обновление uiState.screen = NotesUiScreen.Notes]
+    C --> D[Рекомпозиция: NotesScreen]
+    D -- Системный BackHandler --> E(NotesViewModel.onBack)
+    E --> F[Обновление uiState.screen = NotesUiScreen.Directories]
+```
+
+###Архитектура потока данных в редакторе (EditorViewModel)
+Для предотвращения лишних рекомпозиций всего экрана при каждом нажатии клавиши (вводе символа в BasicTextField), EditorViewModel не использует единый объект Data Class для всего стейта. Вместо этого ключевые свойства разнесены по атомарным наблюдаемым полям:
+
+```kotlin
+graph TD
+    UI[EditorScreen: BasicTextField] -- onValueChange --> VM_Change(EditorViewModel.onContentChange)
+    VM_Change --> VM_State[var content: String by mutableStateOf]
+    VM_State --> UI_Recompose[Быстрая рекомпозиция только текстового поля]
+    
+    UI_Save[Кнопка Назад / Автосохранение] --> VM_Build(EditorViewModel.buildUpdatedNote)
+    VM_Build --> Domain[NotesUseCases.updateNoteUseCase]
+```
+
+##3. Спецификация экранов и UI-компонентов
+####Экраны списков (DirectoriesScreen & NotesScreen)
+Особенности реализации: Активно используют LazyColumn со строго типизированными элементами интерфейса (DirectoryItemUi, NoteItemUi).
+
+####Поиск: 
+Поисковый запрос обрабатывается реактивно через SearchNotesUseCase. Поле ввода интегрировано с модулем онбординга через кастомный модификатор .onboardingTarget().
+
+####Контекстные действия:
+ Длинный тап на папку или заметку активирует режим выбора/удаления, минуя открытие карточки.
+
+####Экран редактора (EditorScreen)
+#####Компонент ввода:
+ Построен на базе BasicTextField с кастомной декорацией (editorPlainTextFieldDecoration), что обеспечивает плавный скролл и адаптацию под экранную клавиатуру.
+
+#####Медиавложения:
+ Поддерживает динамическое добавление элементов ContentItem (изображения, файлы, ссылки). Список вложений фильтруется с помощью расширения .withoutTextItems(), отделяя бинарный контент от тела заметки.
+
+#####Перехват системных кнопок: 
+На экранах авторизации и редактирования явно объявлен BackHandler, предотвращающий случайное закрытие приложения или потерю несохраненного текста.
+
+##4. Внедрение зависимостей (DI) в AppModule.kt
+Регистрация ViewModels и связывание их с доменным слоем (Use Cases) вынесены в модуль Koin. ViewModels списков и онбординга регистрируются через viewModelOf для автоматического разрешения конструкторов, а AuthViewModel настраивается вручную для явной передачи контекста приложения:
+```kotlin
+val appModule = module {
+    // Фабрики Use Cases
+    factory { NotesUseCases(...) }
+    
+    // Презентационный слой
+    viewModelOf(::NotesViewModel)
+    viewModelOf(::OnboardingViewModel)
+    viewModel {
+        AuthViewModel(
+            firebaseAuth = get(),
+            app = androidApplication(),
+            appSessionPreferences = get(),
+            clearLocalDataOnSignOut = get()
+        )
+    }
+}
+```

docs/architecture/onboarding.md

@@ -0,0 +1,62 @@
+# Архитектура и технологический стек
+
+Проект строго следует принципам **Clean Architecture** (Чистой архитектуры) и разделен на изолированные модули. Это обеспечивает независимость бизнес-логики от изменений в UI-слое, базах данных или сторонних ИИ-библиотеках.
+
+<br>
+
+### 🏗 Структура модулей
+
+Здесь представлена схема зависимостей модулей проекта. Каждый модуль выполняет строго определенную роль в архитектуре.
+
+```mermaid
+graph TD
+app[":app (UI & DI Layer)"] --> domain[":domain (Core Business Logic)"]
+data[":data (Data Layer & Room & Firebase)"] --> domain
+ai[":ai (OpenVINO AI Layer)"] --> domain
+```
+
+###📝 Описание роли модулей
+:domain — Слой является центральным и наиболее стабильным слоем приложения. Он содержит бизнес-логику, не зависящую от деталей реализации пользовательского интерфейса, источников данных и внешних фреймворков. Слой спроектирован в соответствии с принципами чистой архитектуры: все зависимости направлены внутрь, а доменные сущности и сценарии использования не имеют ссылок на внешние слои.
+
+:app — Слой UI. Отвечает за представление (Jetpack Compose / MVVM) и внедрение зависимостей (Dependency Injection). Получает данные через domain-слой и отображает их пользователю.
+
+:data — Слой данных. Реализует интерфейсы репозиториев, определенных в модуле domain. Отвечает за работу с локальной БД Room и синхронизацию с Firebase Storage.
+
+:ai — Слой является слоем инфраструктуры, отвечающим за интеграцию с нейросетевыми моделями. Он содержит конкретную реализацию интерфейса NoteAiService, определённого в Domain-слое, и обеспечивает выполнение моделей искусственного интеллекта на устройстве с использованием библиотеки OpenVINO. Слой инкапсулирует всю специфику работы с нейросетевым движком: загрузку моделей, предобработку данных, инференс и постобработку результатов. 
+
+###🛠 Детальный технологический стек
+Спецификация используемых технологий и библиотек, разделенная по уровням абстракции:
+
+####1. Платформа и Язык
+Язык разработки: Kotlin (строгая типизация, Null-Safety, расширения).
+
+Минимальная версия Android SDK: API 26+ (для обеспечения совместимости с современными ИИ-библиотеками).
+
+Целевая версия Android SDK: API 37.
+
+####2. Инференс ИИ на устройстве (On-Device AI)
+Среда исполнения: OpenVINO™ Toolkit (Java API фреймворка, оптимизированный под мобильные процессоры).
+
+Нейросетевые модели: Семейство моделей YOLO (YOLOv10 / YOLOv26).
+
+Адаптивная оптимизация: Архитектура приложения поддерживает динамическое переключение моделей ИИ в зависимости от аппаратных возможностей устройства. Для современных смартфонов с мощными NPU/GPU загружаются старшие версии моделей, а для более старых устройств — легковесные квантованные версии, что гарантирует стабильный FPS и экономию заряда батареи.
+
+####3. Асинхронность и Реактивность
+Управление потоками: Kotlin Coroutines (использование suspend функций, концепции структурной асинхронности, явные вызовы await() для обработки отложенных результатов вычислений нейросетей).
+
+Реактивные потоки: Kotlin Flows (StateFlow / SharedFlow). UI-слой реактивно подписывается на изменения состояний, что исключает утечки памяти и гарантирует корректное обновление интерфейса при фоновой обработке данных (например, во время инференса или синхронизации).
+
+####4. Локальное и Облачное хранение (Data Layer)
+Локальная база данных: Room ORM (абстракция над SQLite с compile-time проверкой SQL-запросов). Используется для мгновенного доступа к заметкам в офлайн-режиме.
+
+Удаленное облачное хранилище: Firebase Storage.
+
+Архитектура синхронизации: Для каждого пользователя в облаке создается изолированная директория, разделенная на два логических блока:
+
+/notes/*.json — структурированные текстовые данные заметок, сериализованные в легковесный формат JSON.
+
+/media/* — связанные бинарные медиафайлы (изображения, аудиозаписи).
+Такой подход обеспечивает высокую скорость синхронизации без необходимости поддержки сложных реляционных СУБД на бэкенде.
+
+####5. Архитектурные инструменты
+Внедрение зависимостей (DI): Koin — легковесный, нативный для Kotlin фреймворк Service Locator. Используется для управления временами жизни объектов (Scopes) и слабой связанности компонентов между модулями.