English | Русский

---

FastH-Core-Stack

FastH-Core-Stack — это высокопроизводительный Fullstack-boilerplate, спроектированный для быстрой разработки асинхронных и защищенных веб-приложений.

Это готовый «фундамент» на базе Clean Architecture, где вся базовая инфраструктура — от Full Auth Lifecycle, админки, Docker-окружения до интерактивного UI — уже настроена и работает «из коробки». Забудь про тяжелые JS-фреймворки и настройку JWT: здесь всё работает на мощи FastAPI и гибкости HTMX, обеспечивая SPA-опыт на чистом Python.

Этот шаблон позволяет вам сосредоточиться на реализации бизнес-идей с первых минут.

📚 Содержание

• 🛠️ Технологический стек
• ✅ Функционал
• 📂 Структура проекта
• 📸 Примеры работы приложения
• ⚙️ Установка и запуск
• 📬 Контакты

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

Компоненты
🐍 Язык: Python 3.14+
⚡ Фреймворк: FastAPI
🪄 Фронтенд: HTMX
📅 Планировщик: APScheduler
🚀 ASGI-сервер: Uvicorn + Gunicorn
🗄️ База Данных: PostgreSQL (asyncpg)
🔁 ORM: SQLAlchemy (async)
🔄 Миграции БД: Alembic
🔐 Аутентификация: FastAPI-Users
🔧 Админка: SQLAdmin
✅ Валидация: Pydantic v2 + pydantic-settings
🧩 Кэширование: Redis + fastapi-cache2
📄 Шаблонизация: Jinja2
🛡️ Защита: slowapi + CORS + CSRF
📧 Почта: aiosmtplib
📦 Менеджер пакетов: uv
🐳 Контейнеризация: Docker + Docker Compose
🧪 Тестирование: Pytest + httpx + faker
📘 Документация: OpenAPI (Swagger UI)
🧹 Форматирование кода: Black
📊 Покрытие тестами: pytest-cov

✅ Функционал

• 🔐 Полный цикл Auth & Security (FastAPI-Users)

  Готовая логика регистрации, входа, верификации email и восстановления пароля. Поддержка сессий на базе БД с безопасными HTTP-only куками.

• 🪄 Интерактивный UI (HTMX + Jinja2)

  SPA-опыт без использования тяжелых JS-фреймворков. Динамическая подгрузка контента, обработка форм и обновление компонентов без перезагрузки страницы.

• 💎 Дизайн в стиле Glassmorphism

  Современный «воздушный» интерфейс с эффектами матового стекла, адаптивной версткой и встроенными индикаторами загрузки (preloaders) для лучшего UX.

• 🧹 Автоматическая гигиена БД (APScheduler)

  Встроенный фоновый планировщик задач, который автоматически очищает просроченные токены и удаляет неподтвержденные аккаунты, поддерживая базу данных в чистоте.

• 🛠️ Профессиональная админ-панель (SQLAdmin)

  Полноценный интерфейс для управления данными: CRUD операции, поиск и фильтрация. Настроено красивое отображение дат и статусов пользователей.

• 🛡️ Защита CSRF, CORS и контроль трафика (Slowapi)

  Встроенный Rate Limiting на критических эндпоинтах для защиты от brute-force и спама. Гибкая настройка CORS для безопасности. Fastapi-csrf-protect для встроенной защиты от межсайтовой подделки запросов, настроенная для работы с HTMX (Double Submit Cookie).

• 🏗️ Современная архитектура (Clean Architecture)

  Четкое разделение на слои: API, Views, Services, Repositories и Models. Проект спроектирован как надежный и масштабируемый фундамент.

• 🚀 Высокая производительность (uv + orjson)

  Использование пакетного менеджера uv для мгновенной установки зависимостей и сборки Docker-образов. Ультра-быстрая сериализация данных через orjson.

• 🗄️ Асинхронная работа с данными (SQLAlchemy 2.0)

  Полностью асинхронное взаимодействие с PostgreSQL через asyncpg. Универсальный базовый репозиторий для минимизации шаблонного кода при работе с БД.

• 🔄 Автоматизация миграций (Alembic)

  Управление схемами базы данных с поддержкой асинхронности. Автоматический накат миграций при запуске контейнера.

• 📧 Асинхронные уведомления (aiosmtplib)

  Отправка системных и транзакционных писем (подтверждение регистрации, сброс пароля) без блокировки основного потока приложения.

• 🧩 Кэширование (Redis + fastapi-cache2)

  Интеграция с Redis для кэширования тяжелых запросов, что значительно снижает нагрузку на базу данных и ускоряет отклик API.

• 📦 Контейнеризация и DevOps (Docker)

  Готовая инфраструктура в Docker Compose: приложение, БД, Redis и PGAdmin запускаются одной командой. Поддержка Hot Reload для быстрой разработки внутри контейнера через watch.

• 🧪 Надежное тестирование (Pytest)

  Настроенная среда для тестирования асинхронного API с использованием HTTPX. Генерация фейковых данных через Faker и отчеты о покрытии кода через pytest-cov.

• 📘 Автодокументация (Swagger)

  Всегда актуальная интерактивная документация API по стандартам OpenAPI, доступная по адресу /docs.

📂 Структура проекта

FastH-Core-Stack/
├── app/                         # Основной пакет приложения
│   ├── actions/                 # CLI-скрипты управления (создание суперпользователя и др.)
│   ├── admin/                   # Конфигурация админ-панели SQLAdmin
│   ├── alembic/                 # История и версии миграций базы данных
│   ├── api/                     # Слой сетевых интерфейсов (API)
│   │   ├── api_v1/              # Первая версия REST API эндпоинтов
│   │   ├── dependencies/        # Инъекции зависимостей (Depends) для роутеров
│   │   ├── webhooks/            # Обработчики входящих уведомлений от внешних систем
│   │   └── __init__.py          # Агрегация и инициализация роутеров
│   ├── core/                    # Системное ядро и инфраструктурные компоненты
│   │   ├── auth/                # Конфигурация безопасности и логика fastapi-users
│   │   ├── cache/               # Настройки и утилиты кэширования (Redis)
│   │   ├── gunicorn/            # Конфигурация WSGI-сервера для продакшена
│   │   ├── config/              # Валидация настроек через pydantic-settings (.env)
│   │   ├── db_helper.py         # Инициализация движка SQLAlchemy и сессий
│   │   ├── limiter.py           # Настройка ограничений частоты запросов (Rate Limiting)
│   │   └── templates.py         # Интеграция и конфигурация Jinja2Templates
│   ├── exceptions/              # Обработка исключений
│   │   ├── custom.py            # Определение пользовательских классов ошибок
│   │   └── handlers.py          # Глобальные обработчики исключений
│   ├── middleware/              # Кастомные middleware
│   ├── models/                  # Описание сущностей базы данных (ORM SQLAlchemy)
│   ├── repositories/            # Слой доступа к данным (Data Access Layer)
│   │   └── crud_manager.py      # Универсальный CRUD-менеджер для работы с моделями
│   ├── schemas/                 # Модели данных Pydantic (DTO) для валидации
│   ├── services/                # Слой бизнес-логики (UseCase Layer)
│   │   └── mailing/             # Почтовый сервис (рассылка уведомлений, подтверждений)
│   ├── static/                  # Статическое содержимое (CSS, JS, Изображения)
│   ├── templates/               # HTML-шаблоны с HTMX и Jinja2
│   ├── utils/                   # Вспомогательные функции общего назначения
│   │   └── case_converter.py    # Функция конвертации имени таблицы
│   ├── views/                   # Роутеры для рендеринга HTML-страниц и HTMX-форм (Frontend-интерфейс)
│   ├── .env                     # Переменные окружения (не отображается в git)
│   ├── .env.template            # Шаблон .env (автоматически заменяет .env, если его нет)
│   ├── alembic.ini              # Конфигурационный файл миграций Alembic
│   ├── create_fastapi_app.py    # Фабрика для сборки и настройки экземпляра FastAPI 
│   ├── main.py                  # Точка входа для запуска в режиме разработки
│   ├── run.py                   # Запуск приложения через Gunicorn (для Docker)
│   └── run_main.py              # Создания и запуск приложения через Gunicorn
├── docker-build/                # Инфраструктурные файлы сборки
│   └── app/
│       ├── Dockerfile           # Инструкции для сборки Docker-образа
│       └── prestart.sh          # Скрипт подготовки БД (миграции + создание админа)
├── tests/                       # Пакет с автоматизированными тестами (Pytest)
├── docker-compose.yml           # Оркестрация контейнеров (App, DB, Redis, PGAdmin)
├── pyproject.toml               # Конфигурация проекта, зависимостей и инструментов (uv)
└── uv.lock                      # Фиксированные версии установленных пакетов

📸 Примеры работы приложения

🖼️ Интерфейс и возможности (Showcase)

Ниже представлены ключевые экраны приложения, демонстрирующие интеграцию FastAPI, HTMX и современный Glassmorphism UI:

• 🏠 Main Hub — Главная страница с адаптивной версткой, готовым футером и навигацией.
• 🔐 Auth Lifecycle — Полноценный цикл регистрации, входа и восстановления пароля через «Забыл пароль».
• 📧 Email Verification — Автоматические страницы уведомлений об успешном или неудачном подтверждении почты.
• 👤 User Profile — Личный кабинет пользователя с управлением данными профиля.
• 🛡️ Security & Access — Форма смены пароля и страницы безопасности (правила сайта).
• 🛠️ Admin Control — Профессиональный интерфейс управления данными (на базе SQLAdmin) для полного контроля над БД.
• 🚦 Error Handling — Кастомные страницы для обработки системных событий:
  • 404 Not Found — Если страница не существует.
  • 429 Rate Limit — Интеллектуальная защита от перегрузок и ботов (Slowapi).
  • 🛡️ Security Error — Специализированная страница для ошибок CSRF (Security Session Expired), помогающая пользователю безопасно обновить сессию.

Все формы работают асинхронно через HTMX, обеспечивая мгновенный отклик без перезагрузки страниц.

⚙️ Установка и запуск

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

В терминале выполните команду:

git clone https://github.com/Mishchenko-Vladimir/FastH-Core-Stack.git

Перейдите в директорию проекта:

cd FastH-Core-Stack

2. Настройка переменных окружения

Заполните файлы .env.template и docker-compose.yml своими значениями.

3. Ваша разработка и настройка приложения

Синхронизируйте виртуальное окружение проекта с зависимостями:

uv sync

Примените миграцию:

cd app
alembic upgrade head
cd ..

Просто редактируйте и добавляйте новые файлы в папку app/, и изменения автоматически применятся в запущенном контейнере.

Локальный запуск (без Docker):

uv run python app/main.py

4. Запуск приложение через Docker

Если вы запускаете образ в Windows, убедись что файлы docker-build/app/prestart.sh и app/run.py, стоят в расширении LF, а не CRLF.

Сборка образа с именем app:

docker compose build app

Запуск сборки (приложения):

docker compose up -d

Остальные команды docker:

• docker compose ps — посмотреть какие контейнеры запущены
• docker compose logs -f app — посмотреть логи приложения
• docker compose stop — остановка приложения
• docker compose down — удаления сборки

Приложение будет доступно по адресу http://localhost:8000, а документация http://localhost:8000/docs

📬 Контакты

💻 Автор: Мищенко Владимир

• GitHub: Mishchenko-Vladimir
• Mail.ru: mishchienko.2001@mail.ru
• Gmail: mishchieko.2001@gmail.com
• Telegram: @VM_Dev

💌 Не забудьте поставить звезду ⭐ на GitHub, если вам понравился проект! 😉

---

↑ Вернуться наверх