VKR 2.0 Digital Advisor

Интеллектуальная платформа для комплексного сопровождения студентов на всех этапах создания выпускной квалификационной работы (ВКР): от формирования первоначальной идеи до успешной защиты.

О проекте

VKR 2.0 Digital Advisor — это веб-приложение, разработанное для автоматизации и оптимизации процесса работы над магистерскими диссертациями. Платформа предоставляет инструменты для:

• Студентов: генерация тем диссертаций с помощью AI, заполнение анкет, отслеживание статуса работы
• Научных руководителей: управление темами студентов, согласование и рецензирование работ
• Руководителей образовательных программ (РОП): мониторинг всех работ по программе, экспорт статистики
• Администраторов: управление пользователями, программами и системными настройками

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

Проект организован как микросервисная архитектура с использованием Docker контейнеров.

Архитектурная схема

Компоненты системы

Frontend

• Технологии: React 19, Vite, React Router
• Контейнер: Nginx для раздачи статических файлов
• Порт: 5173 (внешний), 80 (внутренний)
• Функционал:
  • Пользовательский интерфейс для всех ролей
  • Интеграция с Backend API и LLM Service
  • Отслеживание аналитики через Yandex Metrica

Backend API

• Технологии: FastAPI, SQLAlchemy (async), Alembic
• Порт: 8000
• Функционал:
  • RESTful API для управления пользователями, программами, темами
  • Аутентификация и авторизация по ролям
  • Экспорт данных в XLSX
  • Middleware для сбора метрик
  • Миграции базы данных

LLM Service

• Технологии: FastAPI
• Порт: 8001
• Функционал:
  • Чат с AI помощником для уточнения интересов студентов
  • Генерация структурированных тем диссертаций на основе анкет
  • Интеграция с OpenRouter API (Gemini 2.5 Flash)
  • Кэширование профилей пользователей

База данных

• СУБД: PostgreSQL
• Порт: 5432 (внутренний)
• Хранение: Docker volume
  pgdata
  для персистентности
• Модели: Пользователи, образовательные программы, темы диссертаций, анкеты

pgAdmin

• Назначение: Веб-интерфейс для управления базой данных
• Порт: 8080
• Доступ: Только для администраторов

Сетевая конфигурация

• Выделенная Docker сеть
  vkr-network
  (bridge driver) для изоляции и взаимодействия сервисов
• Все сервисы общаются через внутреннюю сеть по именам контейнеров
• Внешние порты проброшены только для необходимых сервисов

Хранение данных

• Docker volumes:
  • pgdata
    - данные PostgreSQL
  • vkr-data
    - общие данные приложения

Технологический стек

Backend

• Python 3.11+
• FastAPI - современный веб-фреймворк
• SQLAlchemy (async) - ORM для работы с БД
• Alembic - миграции базы данных
• PostgreSQL - реляционная СУБД

Frontend

• React 19 - библиотека для построения UI
• Vite - сборщик и dev-сервер
• React Router - маршрутизация
• React Markdown - отображение markdown контента

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

• Docker - контейнеризация
• Docker Compose - оркестрация контейнеров
• Nginx - веб-сервер для frontend

AI/ML

• OpenRouter API - доступ к LLM моделям
• Google Gemini 2.5 Flash - модель для генерации тем

Роли пользователей

Система поддерживает следующие роли:

• Student - студент, создает темы и заполняет анкеты
• Supervisor - научный руководитель, согласовывает темы и рецензирует работы
• Program Head - руководитель образовательной программы, мониторит все работы по программе
• Admin - администратор системы, полный доступ ко всем функциям

Запуск проекта

Требования

• Docker версии 20.10 или выше
• Docker Compose версии 3.8 или выше

Быстрый старт

1. Клонируйте репозиторий:

2. Создайте файл

   .env
   на основе
   .env.dev
   и настройте переменные окружения:

3. Запустите проект:

4. Дождитесь инициализации всех сервисов (особенно базы данных)

5. Приложение будет доступно:

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:8000
   • API Документация: http://localhost:8000/api/docs
   • LLM Service: http://localhost:8001
   • pgAdmin: http://localhost:8080

Проверка статуса

Для проверки статуса контейнеров:

Или используйте скрипт:

Разработка

Для разработки используйте отдельные конфигурации:

• docker-compose.dev.yml
  - для локальной разработки
• docker-compose.develop.yml
  - для удаленной разработки

Подробнее в DEVELOPMENT.md

Документация

• USER_MANAGEMENT.md - Управление пользователями и создание пользователей разных ролей
• DEVELOPMENT.md - Документация по разработке
• MIGRATIONS.md - Документация по миграциям базы данных
• REMOTE_DEVELOPMENT.md - Удаленная разработка
• HTTPS_SETUP.md - Настройка HTTPS
• LLM_SERVICE_SETUP.md - Настройка LLM сервиса