Общая логика

Что это?

Landy - это конструктор лендинг-страниц (landing page builder) с полнофункциональным backend на FastAPI и frontend на React.js. Позволяет пользователям создавать, редактировать и публиковать лендинги через визуальный интерфейс.

Основная концепция

Проект построен на блочной архитектуре:

  • Каждая страница состоит из блоков

  • Блоки могут быть созданы из готовых шаблонов или с нуля (zero-blocks)

  • Все настройки хранятся в JSON и преобразуются в HTML при публикации

Как это работает?

1. Иерархия данных

Пользователь
    └── Проекты (projects)
         └── Страницы (pages)
              └── Блоки (blocks)
                   ├── Блочные шаблоны (block_templates)
                   └── Zero-блоки (zero_blocks)
                        └── Слои (zero_layers)

2. Основной флоу создания лендинга

  1. Создание проекта - пользователь создает проект с уникальным поддоменом

  2. Создание страниц - в проект добавляются страницы (каждая со своим slug)

  3. Добавление блоков - на страницу добавляются блоки двумя способами:

    • Из шаблонов - готовые блоки с предзаданной структурой

    • Zero-блоки - кастомные блоки, создаваемые с нуля через редактор

  4. Настройка блоков - данные и стили блоков хранятся в JSONB

  5. Публикация - статус страницы меняется на published

  6. Генерация HTML - блочная структура преобразуется в статический HTML

  7. Публичный доступ - HTML сохраняется в /storage/published/

3. Модульная структура

Каждый модуль следует единой структуре:

modules/{module_name}/
├── models.py       # ORM модели (SQLAlchemy)
├── schemas.py      # Схемы валидации (Pydantic)
├── router.py       # API эндпоинты (FastAPI)
└── service.py      # Бизнес-логика

4. Ключевые модули

Auth (аутентификация)

  • Регистрация и вход пользователей

  • JWT токены (access: 30 мин, refresh: 7 дней)

  • Хеширование паролей через bcrypt

Projects (проекты)

  • Управление проектами лендингов

  • Каждый проект имеет уникальный поддомен

  • Привязан к владельцу (user)

Pages (страницы)

  • Страницы внутри проектов

  • Статусы: draft (черновик) или published (опубликовано)

  • Каждая страница имеет title, slug, иконку

Blocks (блоки)

  • Экземпляры блоков на страницах

  • Два типа:

    • Template-based - на основе шаблона

    • Zero-blocks - кастомные блоки

  • Упорядочены по позиции

  • Настройки хранятся в JSONB

Block Templates (шаблоны блоков)

  • Библиотека готовых блоков

  • Организованы по категориям

  • Содержат:

    • Структуру (дерево HTML элементов)

    • Данные по умолчанию

    • Схему настроек

    • URL превью

Zero Blocks (кастомные блоки)

  • Продвинутая система создания блоков с нуля

  • Компоненты:

    • ZeroBaseElement - базовые типы элементов (текст, кнопка, картинка и т.д.)

    • ZeroBlock - контейнер кастомного блока

    • ZeroLayer - отдельные слои/элементы внутри блока

    • Responsive настройки для разных breakpoint'ов

  • Поддержка абсолютного позиционирования

  • Адаптивный дизайн

Media (медиа)

  • Загрузка и управление файлами

  • Поддержка: изображений, видео, документов

  • Макс. размер: 100MB

  • Форматы: jpg, jpeg, png, gif, svg, webp, mp4, webm

5. Templ Editor - Инструмент создания шаблонов

Templ Editor - это визуальный drag-and-drop редактор на React для создания шаблонов блоков администраторами.

Назначение

Этот инструмент используется администраторами для создания готовых шаблонов блоков (block_templates), которые затем становятся доступны обычным пользователям при создании лендингов.

Технологии

  • React 19 - современный фронтенд

  • Tailwind CSS - для стилизации

  • Interact.js - drag-and-drop функциональность

  • Framer Motion - анимации

  • Create React App в качестве сборщика

Основной функционал

Три режима работы:

  1. Builder Mode - работа с JSON-структурой через дерево элементов

  2. Visual Mode - WYSIWYG редактор с визуальным drag-and-drop

  3. JSON Mode - просмотр и копирование готового JSON

Возможности редактирования:

  • Drag-and-drop 27+ типов HTML элементов (div, grid, h1-h6, p, button, img, video, и т.д.)

  • Визуальное перемещение элементов по структуре

  • Применение Tailwind CSS классов

  • Настройка editable стилей (цвет, размеры, текст)

  • Привязка данных к ключам для динамического контента

  • Конфигурация значений по умолчанию

  • Копирование/удаление элементов (Ctrl+D, Delete)

  • Адаптивный превью (Desktop, Tablet, Mobile)

Структура шаблона:

{
  template_name: "Название шаблона",
  category_id: 1,  // Категории
  settings: {
    structure: [],         // Дерево HTML элементов
    editableElements: [],  // Список редактируемых полей
    editableStyles: {}     // Настройки стилей
  },
  default_data: {}         // Данные по умолчанию
}

Интеграция с Landy

  1. Администратор создает шаблон в Templ Editor

  2. Экспортирует JSON

  3. Загружает через API в основной backend (POST /api/block-templates)

  4. Шаблон появляется в библиотеке для всех пользователей

  5. HTML Generator рендерит эти шаблоны при создании лендингов

Флоу данных:

Templ Editor → JSON Export → Landy Backend API → PostgreSQL
                                                      ↓
                                              User Landing Pages

6. HTML Generator (генератор HTML)

Ключевой компонент (/backend/app/utils/html_generator.py):

Преобразует JSON-структуру блоков в готовый HTML:

  • Конвертация CSS стилей (camelCase → kebab-case)

  • Автоматическое добавление единиц px для числовых значений

  • Генерация inline стилей

  • Обработка повторяющихся элементов (сетки, списки)

  • Поддержка медиа-элементов (img, video, audio)

  • Подстановка данных из настроек блока

  • Генерация полного HTML с Tailwind CSS

7. API архитектура

  • RESTful эндпоинты с единым стилем

  • Префикс для всех роутов: /api/

  • Полностью асинхронная работа (async/await)

  • Dependency Injection для БД и аутентификации

  • Автоматическая валидация через Pydantic

  • Автогенерация OpenAPI документации (/api/docs)

8. Аутентификация и безопасность

Регистрация/Вход → Проверка credentials → JWT токен
                                            ↓
Запрос к API → Authorization header → Валидация JWT → Доступ к ресурсу

  • JWT токены с коротким временем жизни

  • Refresh токены для обновления

  • Bcrypt для хеширования паролей

  • CORS настройки

  • Проверка прав доступа к ресурсам

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

PostgreSQL база данных:

  • Асинхронное подключение (asyncpg)

  • Connection pooling (10 соединений, max 20)

  • Миграции через Alembic

Файловое хранилище:

  • /storage/media/ - загруженные пользователями файлы

  • /storage/published/ - сгенерированные HTML страницы

10. Развертывание

Docker Compose - локальная разработка:

  • PostgreSQL контейнер

  • Backend контейнер (FastAPI)

  • Nginx контейнер (reverse proxy)

Ansible - production развертывание:

  • Автоматическая настройка сервера

  • Деплой приложения

  • Настройка SSL (Let's Encrypt)

Основные точки входа

  1. API документация: http://localhost/api/docs

  2. Health check: http://localhost/api/health

  3. Медиа файлы: http://localhost/media/{filename}

  4. Backend: порт 8000 (внутри контейнера)

  5. База данных: PostgreSQL порт 5432

Переменные окружения

Конфигурация через .env файл:

  • DATABASE_URL - строка подключения к PostgreSQL

  • JWT_SECRET_KEY - секрет для JWT токенов

  • JWT_ALGORITHM - алгоритм шифрования (HS256)

  • ACCESS_TOKEN_EXPIRE_MINUTES - время жизни access токена

  • CORS_ORIGINS - разрешенные источники для CORS

  • MAX_UPLOAD_SIZE - макс. размер загружаемого файла

Резюме

Landy - это полнофункциональный конструктор лендингов с:

  • Мультипользовательской системой с JWT аутентификацией

  • Гибкой блочной системой (шаблоны + кастомные zero-блоки)

  • Продвинутой системой адаптивного дизайна

  • Серверной генерацией HTML из JSON структур

  • Управлением медиа-файлами

  • RESTful API с автодокументацией

  • Контейнеризованным развертыванием

  • Автоматизацией инфраструктуры

Архитектура следует принципу разделения ответственности с модульным дизайном, полностью асинхронным I/O и production-ready возможностями.

ПредыдущаяАрхитектура БДСледующаяAPI

Последнее обновление