docs: Add comprehensive project documentation covering architecture, development, and APIs, and update AGENTS.md.

docs/README.md

@@ -0,0 +1,113 @@
+# 📚 Magistr — Система управления университетским расписанием
+
+## Обзор
+
+**Magistr** — веб-приложение для управления расписанием занятий университета. Система поддерживает мультитенантную архитектуру (каждый университет = отдельная база данных), ролевую модель доступа (Администратор, Преподаватель, Студент) и полное управление аудиторным фондом, группами, дисциплинами и преподавательским составом.
+
+- **Продакшн:** [https://magistr.zuev.company](https://magistr.zuev.company)
+- **Локальная разработка:** [http://localhost:80](http://localhost:80)
+
+---
+
+## Стек технологий
+
+| Компонент | Технология |
+|-----------|-----------|
+| **Backend** | Java 17, Spring Boot 3.2.5 |
+| **Frontend** | Vanilla JavaScript (ES6 Modules) + HTML/CSS |
+| **База данных** | PostgreSQL (через Flyway миграции) |
+| **Контейнеризация** | Docker, Docker Compose |
+| **Продакшн** | Kubernetes, Caddy (реверс-прокси) |
+| **Мониторинг** | SigNoz, OpenTelemetry |
+| **CI/CD** | Gitea Actions |
+
+---
+
+## Быстрый старт
+
+### Предварительные требования
+
+- Docker и Docker Compose
+- Git
+
+### Локальный запуск
+
+```bash
+# 1. Клонировать репозиторий
+git clone <repo-url> magistr && cd magistr
+
+# 2. Создать Docker-сеть (если ещё не создана)
+docker network create proxy
+
+# 3. Запустить все сервисы
+docker compose up -d --build
+```
+
+После запуска приложение доступно по адресу: **http://localhost:80**
+
+**Учётные данные по умолчанию:**
+
+| Логин | Пароль | Роль |
+|-------|--------|------|
+| `admin` | `admin` | Администратор |
+| `Тестовый преподаватель` | `1234567890` | Преподаватель |
+
+### Полезные команды
+
+```bash
+# Просмотр логов
+docker compose logs -f backend
+
+# Полный сброс базы данных (удаление данных + повтор миграций)
+docker compose down -v
+docker compose up -d
+
+# Остановка всех сервисов
+docker compose down
+```
+
+---
+
+## Структура проекта
+
+```
+magistr/
+├── backend/                    # Java Spring Boot backend
+│   └── src/main/
+│       ├── java/com/magistr/app/
+│       │   ├── controller/     # REST-контроллеры (10 шт.)
+│       │   ├── model/          # JPA-сущности
+│       │   ├── dto/            # Data Transfer Objects
+│       │   ├── repository/     # Spring Data JPA репозитории
+│       │   ├── config/         # Конфигурация приложения
+│       │   │   └── tenant/     # Мультитенантность
+│       │   └── utils/          # Валидаторы
+│       └── resources/
+│           ├── application.properties
+│           └── db/migration/   # Flyway SQL миграции
+├── frontend/                   # Статический фронтенд
+│   ├── index.html              # Страница авторизации
+│   ├── admin/                  # Админ-панель (деканат)
+│   │   ├── js/views/           # Модули представлений
+│   │   └── css/                # Стили
+│   ├── teacher/                # Интерфейс преподавателя
+│   └── student/                # Интерфейс студента
+├── docs/                       # 📖 Документация (вы здесь)
+├── compose.yaml                # Docker Compose конфигурация
+├── .env                        # Переменные окружения
+└── AGENTS.md                   # Руководство для AI-агентов
+```
+
+---
+
+## 📖 Навигация по документации
+
+| Документ | Содержание |
+|----------|-----------|
+| [Архитектура](ARCHITECTURE.md) | Общая архитектура, мультитенантность, взаимодействие компонентов |
+| [Бизнес-логика](BUSINESS_LOGIC.md) | Ролевая модель, правила расписания, управление ресурсами |
+| [База данных](DATABASE.md) | Схема БД, описание таблиц, Flyway миграции |
+| [REST API](API.md) | Все эндпоинты с примерами запросов и ответов |
+| [Инфраструктура](INFRASTRUCTURE.md) | Docker, Kubernetes, CI/CD, мониторинг |
+| [Разработка](DEVELOPMENT.md) | Code Style, соглашения, инструкции для разработчиков |
+| [Frontend](FRONTEND.md) | Архитектура фронтенда, модули, стили |