Архитектура системы CalmTrader¶

Версия: 1.0 Дата: 13.01.2026 Контракт: order-001-phase1-ru Задача: 2.4.1 Архитектура и схема БД (A4A-30)

1. Обзор системы¶

CalmTrader — AI-психолог для трейдеров, реализованный как Telegram-бот с веб-админкой. Система помогает трейдерам управлять эмоциями через:

Pre-market check-in и post-market reflection
Дыхательные упражнения (/breathe)
Guided медитации (/meditate)
AI-ассистент на базе GPT-4o

1.1 Ключевые характеристики¶

Характеристика	Значение
Архитектура	Микросервисная
Язык backend	Python 3.12
База данных	PostgreSQL 16 + pgvector
Кэш	Redis 7
Object Storage	MinIO
Reverse Proxy	Traefik v3.2
Контейнеризация	Docker + Docker Compose
CI/CD	GitHub Actions

2. Архитектурная диаграмма¶

2.1 Общая схема¶

                                    ┌─────────────────────────────────────────────────────────────┐
                                    │                         INTERNET                            │
                                    └─────────────────────────────────────────────────────────────┘
                                                              │
                                                              ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                         TRAEFIK (Reverse Proxy)                                     │
│                                    Let's Encrypt SSL Auto-Renewal                                   │
│  ┌────────────────┬────────────────┬────────────────┬────────────────┬────────────────────────────┐ │
│  │ api.calmtrader │ bot.calmtrader │ app.calmtrader │admin.calmtrader│ storage.calmtrader.ai      │ │
│  │     .ai        │     .ai        │     .ai        │    .ai         │                            │ │
│  └────────────────┴────────────────┴────────────────┴────────────────┴────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────────────────┘
            │                   │                 │                │                     │
            ▼                   ▼                 ▼                ▼                     ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────────┐
│    API Service    │ │   Bot Service     │ │   Mini App    │ │  Admin Panel  │ │      MinIO        │
│    (FastAPI)      │ │   (aiogram 3.x)   │ │   (Static)    │ │ (Ionic/Angular│ │  (Object Storage) │
│    Port: 8000     │ │   Port: 8080      │ │   Port: 80    │ │   Port: 80    │ │   Port: 9000      │
└───────────────────┘ └───────────────────┘ └───────────────┘ └───────────────┘ └───────────────────┘
            │                   │                                     │                     │
            │                   │                                     │                     │
            ▼                   ▼                                     ▼                     │
┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                        INTERNAL NETWORK                                              │
│  ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────────────────┐│
│  │    PostgreSQL     │ │      Redis        │ │   Agent Service   │ │         Admin Bot             ││
│  │   (pgvector/pg16) │ │    (7-alpine)     │ │   (GPT-4o Agent)  │ │      (Image Gen, etc.)        ││
│  │    Port: 5432     │ │    Port: 6379     │ │    Port: 8001     │ │        Port: 8090             ││
│  └───────────────────┘ └───────────────────┘ └───────────────────┘ └───────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────────────────────────────┘

2.2 Mermaid диаграмма¶

flowchart TB
    subgraph Internet
        Users[Telegram Users]
        Admin[Administrators]
    end

    subgraph Traefik["Traefik Reverse Proxy"]
        SSL[Let's Encrypt SSL]
    end

    subgraph Web["WEB Network (External)"]
        API[API Service<br/>FastAPI :8000]
        Bot[Bot Service<br/>aiogram :8080]
        MiniApp[Mini App<br/>Static :80]
        AdminPanel[Admin Panel<br/>Ionic/Angular :80]
        AdminBot[Admin Bot<br/>:8090]
        Docs[Docs<br/>MkDocs :80]
        MinIO[MinIO<br/>Object Storage :9000]
    end

    subgraph Internal["INTERNAL Network"]
        Postgres[(PostgreSQL<br/>pgvector :5432)]
        Redis[(Redis<br/>Cache :6379)]
        Agent[Agent Service<br/>GPT-4o :8001]
    end

    Users --> |HTTPS| Traefik
    Admin --> |HTTPS| Traefik
    Traefik --> API
    Traefik --> Bot
    Traefik --> MiniApp
    Traefik --> AdminPanel
    Traefik --> AdminBot
    Traefik --> Docs
    Traefik --> MinIO

    Bot --> API
    Bot --> Agent
    Bot --> MinIO
    API --> Postgres
    API --> Redis
    Agent --> Postgres
    AdminBot --> API

3. Компоненты системы¶

3.1 Traefik (Reverse Proxy)¶

Контейнер: traefik Образ: traefik:v3.2 Порты: 80 (HTTP), 443 (HTTPS)

Функции: - Reverse proxy для всех сервисов - Автоматическое получение SSL-сертификатов (Let's Encrypt) - Маршрутизация по доменам - Health checks

Домены: | Домен | Сервис | |-------|--------| | api.calmtrader.ai | API | | bot.calmtrader.ai | Bot webhook | | app.calmtrader.ai | Mini App | | admin.calmtrader.ai | Admin Panel | | admin-bot.calmtrader.ai | Admin Bot | | docs.calmtrader.ai | Documentation | | storage.calmtrader.ai | MinIO (public) |

3.2 PostgreSQL¶

Контейнер: trader-psy-db Образ: pgvector/pgvector:pg16 Порт: 5432 (internal)

Функции: - Основное хранилище данных - Поддержка векторных embeddings (pgvector) - Persistent storage через Docker volume

База данных: trader_psy

3.3 Redis¶

Контейнер: trader-psy-redis Образ: redis:7-alpine Порт: 6379 (internal)

Функции: - Кэширование - Session storage - Append-only persistence

3.4 MinIO (Object Storage)¶

Контейнер: trader-psy-minio Образ: minio/minio Порты: 9000 (API), 9001 (Console)

Функции: - S3-совместимое хранилище - Голосовые сообщения пользователей - Аудио для дыхательных упражнений и медитаций - Изображения (art)

Бакеты: | Бакет | Содержимое | |-------|------------| | voice-messages | Голосовые сообщения пользователей | | breathing-audio | Аудио для дыхательных упражнений | | meditation-audio | Аудио для медитаций | | art | Изображения (watercolor New Yorker style) | | public | Публичные ресурсы (style refs) |

3.5 API Service (FastAPI)¶

Контейнер: trader-psy-api Образ: Custom (apps/api/Dockerfile) Порт: 8000

Функции: - REST API для всех клиентов - CRUD операции с БД - Миграции (Alembic) - Health checks

Зависимости: PostgreSQL, MinIO

Endpoints: См. CLAUDE.md для полного списка

3.6 Agent Service (AI)¶

Контейнер: trader-psy-agent Образ: Custom (apps/agent/Dockerfile) Порт: 8001 (internal)

Функции: - AI-агент на базе GPT-4o - Персонализированные ответы - Onboarding flow - Context-aware диалоги

Зависимости: PostgreSQL, OpenAI API

3.7 Bot Service (Telegram)¶

Контейнер: trader-psy-bot Образ: Custom (apps/bot/Dockerfile) Порт: 8080

Функции: - Telegram webhook handler - Команды: /start, /settings, /checkin, /checkout, /breathe, /meditate, /reset - Voice-to-Text (OpenAI Whisper) - Text-to-Speech (OpenAI TTS, ElevenLabs) - PromptBuilder для AI-промптов

Зависимости: API, Agent, MinIO

3.8 Admin Bot¶

Контейнер: trader-psy-admin-bot Образ: Custom (apps/admin-bot/Dockerfile) Порт: 8090

Функции: - Административный Telegram-бот - Генерация изображений (Midjourney API) - Управление пользователями

Зависимости: API

3.9 Admin Panel¶

Контейнер: trader-psy-admin Образ: Custom (apps/admin/Dockerfile) Порт: 80

Функции: - Веб-панель администратора - User management - Statistics dashboard - Telegram Mini App интеграция

Технологии: Ionic 8, Angular 20+, Tailwind CSS

3.10 Mini App¶

Контейнер: trader-psy-mini-app Образ: Custom (apps/mini-app/Dockerfile) Порт: 80

Функции: - Telegram Mini App для пользователей - Статический HTML/JS

3.11 Documentation¶

Контейнер: trader-psy-docs Образ: Custom (apps/docs/Dockerfile) Порт: 80

Функции: - MkDocs Material documentation - Автогенерация из markdown

4. Сетевая топология¶

4.1 Docker Networks¶

Сеть	Тип	Назначение
web	External	Публичный доступ через Traefik
internal	Bridge	Внутренняя коммуникация сервисов

4.2 Доступ к сервисам¶

┌─────────────────────────────────────────────────────────────────┐
│                         WEB Network                              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐│
│  │ Traefik │ │   API   │ │   Bot   │ │  Admin  │ │  Mini App   ││
│  │         │ │         │ │         │ │  Panel  │ │             ││
│  │         │ │         │ │         │ │         │ │             ││
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────────┘│
│              │           │                                       │
└──────────────│───────────│───────────────────────────────────────┘
               │           │
               ▼           ▼
┌─────────────────────────────────────────────────────────────────┐
│                       INTERNAL Network                           │
│  ┌──────────────┐ ┌─────────┐ ┌─────────┐ ┌───────────────────┐ │
│  │  PostgreSQL  │ │  Redis  │ │  Agent  │ │       MinIO       │ │
│  │              │ │         │ │         │ │                   │ │
│  └──────────────┘ └─────────┘ └─────────┘ └───────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

5. Потоки данных¶

5.1 Основной пользовательский flow¶

sequenceDiagram
    participant U as User (Telegram)
    participant B as Bot Service
    participant A as Agent Service
    participant API as API Service
    participant DB as PostgreSQL
    participant M as MinIO

    U->>B: Сообщение / Команда
    B->>API: POST /users (upsert)
    API->>DB: INSERT/UPDATE user
    B->>A: Запрос к AI агенту
    A->>DB: Получить контекст пользователя
    A->>A: Генерация ответа (GPT-4o)
    A->>B: Ответ агента
    B->>API: POST /messages (save)
    API->>DB: INSERT message
    B->>U: Ответ пользователю

5.2 Voice Message Flow¶

sequenceDiagram
    participant U as User
    participant B as Bot
    participant W as Whisper API
    participant M as MinIO
    participant A as Agent

    U->>B: Voice message
    B->>W: Transcribe audio
    W->>B: Text transcript
    B->>M: Upload voice file
    B->>A: Process text
    A->>B: AI response
    B->>B: TTS (OpenAI/ElevenLabs)
    B->>U: Voice response

5.3 Breathing Exercise Flow¶

sequenceDiagram
    participant U as User
    participant B as Bot
    participant API as API
    participant M as MinIO

    U->>B: /breathe
    B->>U: Выбор техники (inline buttons)
    U->>B: Выбор (box_breathing)
    B->>API: GET /breathing-audio/parts
    API->>M: Get audio files
    M->>API: Audio parts
    API->>B: Audio URLs
    B->>B: Assemble audio
    B->>U: Voice message + transcript

6. Deployment и CI/CD¶

6.1 Инфраструктура¶

Хостинг: Hetzner Cloud IP: 65.21.108.205 SSH alias: trader-psy Path: /opt/trader-psy

6.2 CI/CD Pipeline¶

flowchart LR
    A[Push to main] --> B[GitHub Actions]
    B --> C[Lint: ruff check]
    C --> D[Test: pytest]
    D --> E[Deploy: SSH]
    E --> F[git pull]
    F --> G[docker compose up]
    G --> H[Migrations: alembic]
    H --> I[Health check]
    I --> J[Notify users]

Файл: .github/workflows/deploy.yml

6.3 Docker Volumes¶

Volume	Назначение
postgres-data	Данные PostgreSQL
redis-data	Данные Redis
traefik-certificates	SSL-сертификаты
minio-data	Файлы MinIO

7. Безопасность¶

7.1 SSL/TLS¶

Provider: Let's Encrypt (ACME)
Auto-renewal: Yes (Traefik)
Min TLS: 1.2

7.2 Сетевая изоляция¶

Внутренние сервисы (PostgreSQL, Redis, Agent) недоступны извне
Публичный доступ только через Traefik
MinIO доступен публично только для bucket public

7.3 Secrets Management¶

Все секреты хранятся в .env файле на сервере: - TELEGRAM_BOT_TOKEN - POSTGRES_PASSWORD - MINIO_ROOT_PASSWORD - OPENAI_API_KEY - ELEVENLABS_API_KEY - APIFRAME_API_KEY

7.4 Рекомендации (TODO)¶

Добавить rate limiting в Traefik
Настроить Fail2Ban
Внедрить Sentry для мониторинга ошибок
Провести security audit (A4A-23)

8. Мониторинг¶

8.1 Health Checks¶

Сервис	Endpoint	Интервал
API	GET /health	30s
PostgreSQL	pg_isready	10s
Redis	redis-cli ping	10s
MinIO	/minio/health/live	30s

8.2 Логирование¶

Docker logs: docker compose logs -f <service>
Structured logging в API/Bot (Python logging)

Приложения¶

A. Команды управления¶

# Подключение к серверу
ssh trader-psy

# Статус сервисов
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml ps"

# Логи
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml logs -f"

# Рестарт
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml restart"

# Миграции
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml exec api alembic upgrade head"

B. Связанные документы¶

Database Schema — Схема базы данных (2.4.3)
Контракт order-001 — Требования Phase 1
CLAUDE.md — Инструкции для разработки

Документ создан в рамках выполнения контракта order-001-phase1-ru