Инженерный разбор

Как устроен этот сайт

Инженерный разбор production-подхода: архитектура, локализация, контент-редактирование, качество, безопасность и инфраструктура в одной базе знаний.

Исходный код Открыть матрицу

Задача

Сайт объединяет статьи, матрицу компетенций и разбор собственной архитектуры. Он должен быть полезным читателям, удобным для автора и одновременно показывать реальные инженерные решения, а не только список технологий.

Архитектура

Backend

Litestar, SQLAlchemy, Dishka и PostgreSQL образуют API-first backend с явными границами между доменом, HTTP-слоем, инфраструктурой и хранением. Приватная база знаний расширяет общий типизированный item отдельными 1:1-таблицами вместо универсального JSON/EAV, а каждая операция изолируется по автору.

LitestarSQLAlchemyPostgreSQLDishkaTaskIQ

Frontend

Angular hybrid SSR/CSR и backend-driven i18n дают SEO для публичных страниц, а read-only матрица и статьи отделены от protected workspaces: контентом управляют владелец, администраторы и модераторы, а командой — владелец и администраторы.

AngularSSRTypeScriptBootstrap

Infrastructure

nginx, Docker, MinIO с S3-compatible media storage, Valkey и TaskIQ разделяют edge routing, файлы, кэш, фоновые задачи и runtime frontend/backend контейнеров, а публичный трафик переключается между blue/green слотами после health checks. Приватные файлы базы знаний вынесены в отдельный MinIO bucket без публичных URL: backend проверяет автора и стримит содержимое, а публичный S3 edge отвечает 404. Edge nginx самовосстанавливается после устойчивого отказа локального liveness endpoint и использует restart policy для перезапуска Docker или VPS.

nginxDockerMinIOValkeyGitHub Actions

Безопасный AI-доступ

Семь Agent REST-операций смонтированы в основном Litestar-приложении без отдельного процесса и Unix-сокета. Приватную границу сохраняет отдельный WireGuard-bound nginx mTLS-listener с точным allowlist; публичный listener возвращает 404 для внутреннего пути и удаляет поддельный certificate header. Локальный stdio MCP-мост открывает ровно пять Draft-only операций без publish, generic CRUD, SQL, shell или URL fetch. Упрощение осознанно оставляет общими с backend процесс, роль БД, секреты и доступность: изоляция private application network и доверие к nginx остаются частью boundary.

Litestar RESTlocal stdio MCPWireGuardmTLSDraft-only

Инженерные решения

Clean Architecture: доменная логика не зависит от Litestar, SQLAlchemy или внешних сервисов.
RU/EN локализация разделена на UI-каталог и контентные поля, чтобы не смешивать интерфейс со статьями и матрицей.
Privacy-safe аналитика считает просмотры и реакции без cookies, raw IP, user-agent или сторонних идентификаторов.
Деплой оформлен как управляемый release process с ручным запуском: runtime-конфигурация собирается из manifest, CI quality gates отделены от deploy workflow, ручное подтверждение production environment остаётся явным, а blue/green переключение с health checks снижает риск релиза.

Качество и эксплуатация

Качество держится на коротких проверках: стиль, типы, unit/integration тесты, безопасность, SSR smoke, производительность и SQL-планы. Они остаются CI evidence перед релизом, а production deploy запускается вручную и переключает blue/green трафик только после health checks. В эксплуатации фоновые задачи, кэш, файлы и runtime контейнеры разделены по ответственности; публичные ассеты обслуживаются с CSP и immutable caching.

Что дальше

Ближайшие направления: RSS/Atom, публичный roadmap и дальнейшая работа над наблюдаемостью, производительностью и качеством контента.

Перейти к статьям