Update README.md with architecture diagram

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

README.md

@@ -1,63 +1,193 @@
-# Alexander Smart Speaker
+<div align="center">
 
-Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков.
+# 🎙️ Alexander Smart Speaker
 
-## Что умеет
-- Активация по ключевому слову `Alexandr`.
-- Диалог с AI (Perplexity) с сохранением контекста.
-- Перевод RU ↔ EN с озвучиванием.
-- Погода по умолчанию и по названию города.
-- Будильники, таймеры и секундомеры.
-- Управление громкостью системы.
-- Управление Spotify (play/pause/next/current track).
-- Игра в города.
+**Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков**
 
-## Технологии
-- Wake word: `pvporcupine`
-- STT: `deepgram-sdk`
-- TTS: `Silero` (`torch`, `torchaudio`)
-- AI: Perplexity API
-- Погода: Open-Meteo
-- Музыка: Spotify Web API (`spotipy`)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](https://www.linux.org/)
+[![License](https://img.shields.io/github/license/your-username/alexander_smart-speaker)](LICENSE.txt)
 
-## Требования
-- Linux
-- Python 3.9+
-- Системные пакеты:
+</div>
+
+## ✨ Возможности
+
+| Функция | Описание |
+|--------|----------|
+| 🔊 **Активация по ключевому слову** | Активация по команде `Alexandr` |
+| 🧠 **Диалог с AI** | Взаимодействие с Perplexity с сохранением контекста |
+| 🌐 **Перевод** | Перевод RU ↔ EN с озвучиванием |
+| 🌤️ **Погода** | Информация о погоде по умолчанию и по названию города |
+| ⏰ **Таймеры и будильники** | Управление таймерами, будильниками и секундомерами |
+| 🔊 **Управление громкостью** | Регулировка системной громкости |
+| 🎵 **Spotify интеграция** | Управление воспроизведением (play/pause/next/current track) |
+| 🌍 **Игра в города** | Классическая игра в города |
+
+## 🏗️ Архитектура проекта
+
+### Диаграмма взаимодействия компонентов
+
+```mermaid
+graph TB
+    subgraph "Основной цикл (main.py)"
+        A[Бесконечный цикл] --> B{Режим активации}
+        B -->|Ожидание wake word| C[wait_for_wakeword]
+        B -->|Режим диалога| D[listen в режиме follow-up]
+        C --> E[Прослушивание команды]
+        D --> E
+        E --> F[Анализ команды]
+    end
+    
+    subgraph "Аудио подсистема (app/audio/)"
+        C1[wakeword.py<br/>- wait_for_wakeword<br/>- check_wakeword_once]
+        E1[stt.py<br/>- listen<br/>- get_recognizer]
+        G1[tts.py<br/>- speak<br/>- initialize]
+        H1[sound_level.py<br/>- parse_volume_text<br/>- set_volume]
+        
+        C1 -.-> E1
+        E1 -.-> G1
+        H1 -.-> G1
+    end
+    
+    subgraph "Ядро (app/core/)"
+        F1[commands.py<br/>- is_stop_command<br/>- _normalize_text]
+        F2[ai.py<br/>- ask_ai_stream<br/>- translate_text]
+        F3[cleaner.py<br/>- clean_response]
+        F4[config.py<br/>- Настройки проекта]
+        F5[smalltalk.py<br/>- get_smalltalk_response]
+        
+        F --> F1
+        F --> F2
+        F --> F3
+        F --> F5
+    end
+    
+    subgraph "Функции (app/features/)"
+        I1[weather.py<br/>- get_weather_report]
+        I2[timer.py<br/>- get_timer_manager]
+        I3[alarm.py<br/>- get_alarm_clock]
+        I4[stopwatch.py<br/>- get_stopwatch_manager]
+        I5[music.py<br/>- get_music_controller]
+        I6[cities_game.py<br/>- get_cities_game]
+        
+        F --> I1
+        F --> I2
+        F --> I3
+        F --> I4
+        F --> I5
+        F --> I6
+    end
+    
+    subgraph "Обработка команд"
+        F --> J{Тип команды}
+        J -->|Small talk| K[get_smalltalk_response]
+        J -->|Повтор| L[Повтор последнего ответа]
+        J -->|Стоп| M[is_stop_command]
+        J -->|Таймер| N[parse_command timer]
+        J -->|Будильник| O[parse_command alarm]
+        J -->|Секундомер| P[parse_command stopwatch]
+        J -->|Громкость| Q[parse_volume_text + set_volume]
+        J -->|Погода| R[get_weather_report]
+        J -->|Музыка| S[parse_command music]
+        J -->|Перевод| T[parse_translation_request]
+        J -->|Города| U[handle cities_game]
+        J -->|AI| V[ask_ai_stream]
+    end
+    
+    subgraph "Ответ пользователю"
+        K --> W[clean_response]
+        L --> W
+        M --> W
+        N --> W
+        O --> W
+        P --> W
+        Q --> W
+        R --> W
+        S --> W
+        T --> W
+        U --> W
+        V --> W
+        
+        W --> X[speak]
+        X --> Y[Возврат в режим ожидания]
+        Y --> A
+    end
+    
+    %% Connections
+    C1 -.-> A
+    E1 -.-> F
+    G1 -.-> X
+    F2 -.-> V
+    F3 -.-> W
+    I1 -.-> R
+    I2 -.-> N
+    I3 -.-> O
+    I4 -.-> P
+    I5 -.-> S
+    I6 -.-> U
+    
+    style A fill:#e1f5fe
+    style F fill:#f3e5f5
+    style X fill:#e8f5e8
+    style Y fill:#fff3e0
+</graph>
+```
+
+## 🛠️ Технологии
+
+| Компонент | Технология |
+|-----------|------------|
+| **Wake word** | `pvporcupine` |
+| **STT** | `deepgram-sdk` |
+| **TTS** | `Silero` (`torch`, `torchaudio`) |
+| **AI** | Perplexity API |
+| **Погода** | Open-Meteo |
+| **Музыка** | Spotify Web API (`spotipy`) |
+
+## 📋 Требования
+
+- **ОС**: Linux
+- **Python**: 3.9+
+- **Системные пакеты**:
 
 ```bash
 sudo apt-get update
 sudo apt-get install -y portaudio19-dev libasound2-dev mpg123
 ```
 
-Для управления громкостью нужен `pactl` или `amixer` (обычно из `pulseaudio-utils`/`alsa-utils`).
+> 💡 Для управления громкостью необходим `pactl` или `amixer` (обычно из `pulseaudio-utils`/`alsa-utils`).
 
-## Установка
+## 🚀 Установка
 
+1. **Клонируйте репозиторий**:
 ```bash
 git clone https://github.com/your-username/alexander_smart-speaker.git
 cd alexander_smart-speaker
+```
 
+2. **Настройте виртуальное окружение**:
+```bash
 python -m venv venv
-source venv/bin/activate
+source venv/bin/activate  # или venv\Scripts\activate на Windows
 pip install -r requirements.txt
 ```
 
-## Настройка `.env`
+## ⚙️ Настройка
 
+1. **Создайте файл конфигурации**:
 ```bash
 cp .env.example .env
 ```
 
-Минимально обязательные переменные:
+2. **Обязательные переменные окружения**:
 
 ```ini
-PERPLEXITY_API_KEY=...
-DEEPGRAM_API_KEY=...
-PORCUPINE_ACCESS_KEY=...
+PERPLEXITY_API_KEY=your_perplexity_api_key_here
+DEEPGRAM_API_KEY=your_deepgram_api_key_here
+PORCUPINE_ACCESS_KEY=your_porcupine_access_key_here
 ```
 
-Полный пример (как в `.env.example`):
+3. **Полная конфигурация** (как в `.env.example`):
 
 ```ini
 PERPLEXITY_API_KEY=your_perplexity_api_key_here
@@ -74,7 +204,7 @@ SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
 SPOTIFY_REDIRECT_URI=http://localhost:8888/callback
 ```
 
-## Запуск
+## ▶️ Запуск
 
 ```bash
 make run
@@ -82,41 +212,62 @@ make run
 python run.py
 ```
 
-## Примеры голосовых команд
-- Активация: `Alexandr`
-- Диалог: `Почему небо голубое?`
-- Погода: `Какая сейчас погода?`, `Погода в Москве`
-- Перевод: `Переведи на английский: как дела`
-- Таймер: `Поставь таймер на 5 минут`
-- Будильник: `Поставь будильник на 7:30`, `Будильник по будням в 8:00`
-- Секундомер: `Запусти секундомер`, `Покажи активные секундомеры`
-- Громкость: `Громкость 5`
-- Spotify: `Включи музыку`, `Пауза`, `Что сейчас играет`
-- Игра: `Давай сыграем в города`
-- Остановка/прерывание: `Стоп`, `Хватит`, `Повтори`
+## 🗣️ Примеры голосовых команд
 
-## Полезные команды
+| Категория | Команды |
+|-----------|---------|
+| **Активация** | `Alexandr` |
+| **Диалог** | `Почему небо голубое?` |
+| **Погода** | `Какая сейчас погода?`, `Погода в Москве` |
+| **Перевод** | `Переведи на английский: как дела` |
+| **Таймер** | `Поставь таймер на 5 минут` |
+| **Будильник** | `Поставь будильник на 7:30`, `Будильник по будням в 8:00` |
+| **Секундомер** | `Запусти секундомер`, `Покажи активные секундомеры` |
+| **Громкость** | `Громкость 5` |
+| **Spotify** | `Включи музыку`, `Пауза`, `Что сейчас играет` |
+| **Игра** | `Давай сыграем в города` |
+| **Остановка** | `Стоп`, `Хватит`, `Повтори` |
 
-```bash
-make run          # запуск ассистента
-make check        # базовая проверка проекта
-make qwen-context # собрать контекст проекта
+## 🛠️ Полезные команды
+
+| Команда | Назначение |
+|---------|------------|
+| `make run` | Запуск ассистента |
+| `make check` | Базовая проверка проекта |
+| `make qwen-context` | Собрать контекст проекта |
+
+## 📁 Структура проекта
+
+```
+alexander_smart-speaker/
+├── run.py                 # точка входа
+├── app/
+│   ├── main.py           # главный цикл ассистента
+│   ├── audio/            # wake word, STT, TTS, громкость
+│   ├── core/             # конфиг, AI, роутинг команд, утилиты
+│   └── features/         # погода, будильник, таймер, секундомер, музыка, города
+├── assets/               # модели и звуки
+├── data/                 # сохраненные будильники/таймеры/секундомеры
+└── scripts/              # скрипты для установки и обслуживания
 ```
 
-## Структура проекта
-- `run.py` - точка входа.
-- `app/main.py` - главный цикл ассистента.
-- `app/audio/` - wake word, STT, TTS, громкость.
-- `app/core/` - конфиг, AI, роутинг команд, утилиты.
-- `app/features/` - погода, будильник, таймер, секундомер, музыка, города.
-- `assets/` - модели и звуки.
-- `data/` - сохраненные будильники/таймеры/секундомеры.
+## 🔧 Диагностика проблем
 
-## Диагностика проблем
-- Ошибки STT/AI: проверьте ключи в `.env`.
-- Нет звука: проверьте системное устройство вывода и утилиты `pactl`/`amixer`.
-- Не играет будильник/таймер: убедитесь, что установлен `mpg123`.
-- Spotify не управляется: проверьте `SPOTIFY_*`, авторизацию и наличие активного устройства.
+| Проблема | Решение |
+|----------|---------|
+| Ошибки STT/AI | Проверьте ключи в `.env` |
+| Нет звука | Проверьте системное устройство вывода и утилиты `pactl`/`amixer` |
+| Не играет будильник/таймер | Убедитесь, что установлен `mpg123` |
+| Spotify не управляется | Проверьте `SPOTIFY_*`, авторизацию и наличие активного устройства |
 
-## Лицензия
-MIT, см. `LICENSE.txt`.
+## 📄 Лицензия
+
+MIT, см. [LICENSE.txt](LICENSE.txt).
+
+---
+
+<div align="center">
+
+**Если вам понравился проект, поставьте ⭐ звезду!**
+
+</div>