logboard/docs/project-structure.md

# Структура проекта LogBoard+

**Автор:** Сергей Антропов  
**Сайт:** https://devops.org.ru

## Обзор структуры

LogBoard+ имеет модульную архитектуру с четким разделением ответственности. Проект организован в соответствии с лучшими практиками Python и FastAPI.

## Дерево файлов

```
logboard/
├── app/                    # Основная папка приложения
│   ├── __init__.py        # Инициализация пакета
│   ├── app.py             # Основное приложение FastAPI
│   ├── excluded_containers.json  # Исключенные контейнеры
│   ├── api/               # API модули
│   │   ├── __init__.py
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── router.py  # Основной роутер API
│   │       └── endpoints/ # API endpoints
│   │           ├── __init__.py
│   │           ├── auth.py        # Аутентификация
│   │           ├── containers.py  # Управление контейнерами
│   │           ├── logs.py        # Логи
│   │           ├── pages.py       # HTML страницы
│   │           ├── settings.py    # Настройки
│   │           └── websocket.py   # WebSocket API
│   ├── core/              # Основные модули
│   │   ├── __init__.py
│   │   ├── auth.py        # Аутентификация и авторизация
│   │   ├── config.py      # Конфигурация приложения
│   │   ├── docker.py      # Работа с Docker API
│   │   └── logger.py      # Система логирования
│   ├── models/            # Модели данных
│   │   ├── __init__.py
│   │   └── auth.py        # Модели аутентификации
│   ├── static/            # Статические файлы
│   │   ├── css/           # CSS стили
│   │   │   ├── index.css  # Основные стили
│   │   │   ├── login.css  # Стили страницы входа
│   │   │   └── error.css  # Стили страниц ошибок
│   │   ├── js/            # JavaScript файлы
│   │   │   ├── index.js   # Основная логика
│   │   │   ├── login.js   # Логика входа
│   │   │   └── error.js   # Логика ошибок
│   │   ├── images/        # Изображения
│   │   │   └── favicon.ico # Иконка сайта
│   │   └── fonts/         # Шрифты
│   └── templates/         # HTML шаблоны
│       ├── index.html     # Главная страница
│       ├── login.html     # Страница входа
│       └── error.html     # Страницы ошибок
├── docs/                  # Документация
│   ├── index.md          # Главная страница документации
│   ├── installation.md   # Установка и настройка
│   ├── configuration.md  # Конфигурация
│   ├── api.md            # API документация
│   ├── websocket.md      # WebSocket API
│   ├── security.md       # Безопасность
│   ├── troubleshooting.md # Устранение неполадок
│   └── project-structure.md # Структура проекта
├── snapshots/             # Снимки логов
├── screenshots/           # Скриншоты интерфейса
├── .env                   # Переменные окружения (создается из env.example)
├── env.example            # Пример переменных окружения
├── docker-compose.yml     # Конфигурация Docker Compose
├── Dockerfile            # Образ Docker
├── requirements.txt      # Зависимости Python
├── start.sh              # Скрипт запуска
└── README.md             # Документация проекта
```

## Описание модулей

### `app/app.py`
Основной файл приложения FastAPI. Содержит:
- Инициализацию FastAPI приложения
- Подключение статических файлов
- Обработчики исключений
- Подключение роутеров

### `app/api/v1/`
API модули версии 1:
- **router.py** - Основной роутер, объединяющий все endpoints
- **endpoints/** - Отдельные модули для каждого типа API

### `app/api/v1/endpoints/`
API endpoints разделены по функциональности:
- **auth.py** - Аутентификация (login, logout, me)
- **containers.py** - Управление контейнерами (список, проекты)
- **logs.py** - Работа с логами (получение, статистика, снимки)
- **pages.py** - HTML страницы (главная, вход, ошибки)
- **settings.py** - Настройки приложения
- **websocket.py** - WebSocket API для real-time логов

### `app/core/`
Основные модули приложения:
- **auth.py** - Логика аутентификации и авторизации
- **config.py** - Конфигурация приложения из переменных окружения
- **docker.py** - Работа с Docker API
- **logger.py** - Система логирования

### `app/models/`
Pydantic модели данных:
- **auth.py** - Модели для аутентификации (UserLogin, Token)

### `app/static/`
Статические файлы:
- **css/** - CSS стили для всех страниц
- **js/** - JavaScript файлы с логикой интерфейса
- **images/** - Изображения и иконки
- **fonts/** - Шрифты

### `app/templates/`
HTML шаблоны:
- **index.html** - Главная страница с интерфейсом
- **login.html** - Страница входа в систему
- **error.html** - Шаблон для страниц ошибок

## Принципы организации

### 1. Модульность
Каждый модуль отвечает за свою область ответственности:
- API endpoints разделены по функциональности
- Core модули содержат бизнес-логику
- Models определяют структуру данных

### 2. Версионирование API
API организован по версиям (`v1/`), что позволяет:
- Добавлять новые версии без нарушения совместимости
- Поддерживать несколько версий одновременно
- Плавно мигрировать пользователей

### 3. Разделение статических файлов
Статические файлы разделены по типам:
- CSS для стилизации
- JavaScript для интерактивности
- Изображения для визуальных элементов

### 4. Конфигурация
Все настройки централизованы в `app/core/config.py`:
- Загрузка из переменных окружения
- Значения по умолчанию
- Валидация конфигурации

## Добавление новых модулей

### Новый API endpoint
1. Создайте файл в `app/api/v1/endpoints/`
2. Определите роутер с нужными маршрутами
3. Подключите в `app/api/v1/router.py`

### Новый core модуль
1. Создайте файл в `app/core/`
2. Добавьте необходимые импорты
3. Обновите документацию

### Новые статические файлы
1. Добавьте файлы в соответствующие папки `app/static/`
2. Обновите ссылки в HTML шаблонах
3. Проверьте корректность загрузки

## Лучшие практики

1. **Именование файлов** - используйте snake_case для Python файлов
2. **Документация** - добавляйте docstrings ко всем функциям
3. **Типизация** - используйте type hints везде, где возможно
4. **Обработка ошибок** - добавляйте try-catch блоки
5. **Логирование** - используйте централизованную систему логирования