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

Что это

LMS Course Generator — система автоматической генерации онлайн-курсов из исходных материалов (PDF, текст, web-ссылки) с помощью AI (Google Gemini). Результат — структурированный мультимодальный курс (текст, тесты, карточки, код-раннер, изображения, аудио, видео) с автоматической проверкой качества и адаптивными подсказками студентам.

Система мультишкольная (multi-tenant): каждая школа изолирована через PostgreSQL RLS (Row-Level Security).

Архитектура в одном абзаце

Backend — FastAPI + Temporal + PostgreSQL + MinIO. Frontend — Next.js 15 (App Router) + Tailwind + собственная дизайн-система .lms-*. Runtime LLM — только Gemini через единый клиент packages/shared/llm_client.py с cost-tracking и бюджет-лимитами. Фоновые пайплайны — Temporal workflows; каждый AI-агент — это отдельный Python-модуль в packages/agents/<slug>/.

Стек (LOCKED — см. `docs/PROJECT_MANIFEST.md` §2)

Слой	Технология
Язык backend	Python 3.12 + Pydantic v2
API	FastAPI (async)
Workflows	Temporal (Python SDK)
БД	PostgreSQL 16 (pgvector, JSONB, FTS, RLS)
Object storage	MinIO (S3-совместимо)
LLM	Google Gemini (Flash / Pro / Reasoning / TTS / Embedding / Veo / Nano Banana / Lyria)
Code runner	Judge0
Frontend	Next.js 15 + React 19
Стилизация	Design tokens + semantic `.lms-*` классы (см. ADR-0014)
Форматтеры	ruff (Python), biome (TS)
Mobile	Capacitor поверх того же Next.js (Phase 6+)

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

┌─────────────────┐
│ platform_admin  │  Видит всё. Управляет школами/провайдерами/биллингом глобально.
└────────┬────────┘
         │ создаёт
         ▼
┌─────────────────┐
│ school_admin    │  Администрирует ОДНУ школу. Биллинг школы. Аналитика. Преподаватели.
└────────┬────────┘
         │ назначает
         ▼
┌─────────────────┐
│ teacher         │  Создаёт и публикует курсы ВНУТРИ своей школы.
└────────┬────────┘
         │ обучает
         ▼
┌─────────────────┐
│ student         │  Проходит курсы. Получает адаптивные подсказки.
└─────────────────┘

Разграничение — через user_memberships (user × school × role) и PostgreSQL RLS. Подробно — см. 05-developer.md и 08-glossary.md.

Быстрый старт (любая роль, dev-кластер)

Открой http://127.0.0.1:3500/login.
Демо-учётки (пароль у всех — change_me_locally):

Email Роль

admin@local platform_admin

school_admin@local school_admin (демо-школа)

teacher@local teacher (демо-школа)

student@local student (демо-школа)
После входа попадаешь в /dashboard.
Дальше — см. файл для своей роли:

Email	Роль
`admin@local`	platform_admin
`school_admin@local`	school_admin (демо-школа)
`teacher@local`	teacher (демо-школа)
`student@local`	student (демо-школа)

Сессии и авторизация

Access-токен живёт 15 минут, refresh — 2 месяца (rolling).
Вход с нового устройства присоединяется к существующей сессии и продлевает её (не создаёт вторую). Единственный способ разлогиниться — /auth/logout.
Токены на фронте хранятся в sessionStorage под ключом access_token.

Жизненный цикл курса (для понимания)

 [PDF/URL/текст]  ──▶ Harvester ──▶ DocumentIngestor ──▶ EmbeddingComputer
                                                                 │
                                                                 ▼
                                                             Curator
                                                                 │
                                                                 ▼
                                          Architect (структура модулей/лекций)
                                                                 │
                                                                 ▼
                                   Composer (генерит блоки 11 типов)
                                                                 │
                                                ┌────────────────┴────────────────┐
                                                ▼                                 ▼
                                         NarrativeKeeper                  GlossaryCurator
                                                \_______________________________/
                                                                 │
                                                                 ▼
                                                             Critic
                                                   (36 проверок, пишет verdict)
                                                                 │
                          ┌──────────────────────────────────────┤
                          ▼                                      ▼
                       REJECT                                 APPROVE
                          │                                      │
                          ▼                                      ▼
                       Rework                                Publisher
                                                                 │
                                                                 ▼
                                                    published_courses (v1, v2, ...)
                                                                 │
                                                       Студент проходит
                                                                 │
                                                                 ▼
                                                  AdaptiveSupplementer
                                          (если ошибся → подсказка на лету)

Что где лежит в репо (краткая карта)

packages/
  core/           FastAPI-приложение и роутеры (/auth, /courses, /media, /billing, /learner, /adaptive, ...)
  agents/         Все runtime AI-агенты (1 папка = 1 агент)
  workflows/      Temporal workflows и activities
  block_types/    Плагинная система типов блоков (schema + generator + validator + renderer)
  shared/         llm_client, prompt_registry, minio_client, общие утилиты
  billing/        Провайдеры платежей (stripe, vipps, paypal, mock)

frontend/
  app/            Next.js App Router (login, dashboard, courses, analytics, billing, demo, ...)
  app/globals.css Вся дизайн-система .lms-* (~720 строк)

infra/
  docker-compose.dev.yml   Postgres + Temporal + MinIO + Temporal UI (loopback only)

docs/
  PROJECT_MANIFEST.md      Единственный источник правды об архитектуре
  decisions/               ADR-0001..0015
  agents/                  Контракты отдельных агентов

scripts/
  backup_db_to_minio.sh    Дамп БД перед каждой миграцией (ОБЯЗАТЕЛЬНО)
  bootstrap.py             Dev-школа + 4 демо-пользователя
  seed_methodologies.py    Методики обучения

tests/                     pytest, 426+ тестов на момент Phase 5
tools/mcp-servers/         MCP-серверы для IDE-ассистента (lms-db, lms-agents, lms-gemini, lms-methodology)
manual/                    ← вы здесь

Куда идти дальше

Техническая глубина — docs/PROJECT_MANIFEST.md, docs/decisions/*.
Процесс разработки — 05-developer.md.
Поиск по API — 07-api-reference.md.