Backend-сервисы AIOps построены на принципах Clean Architecture, Domain-Driven Design и Event-Driven Architecture.

По задаче

Архитектурные паттерны

Clean Architecture

Все сервисы следуют четкому разделению на слои:

Core (core/) — Domain Layer: - Domain entities (Pydantic models) - Repository protocols (ABC) - Domain services (бизнес-логика) - DTOs и errors

Use Cases (use_cases/) — Application Layer: - Use case implementations - Orchestration logic - Зависимости только от core/

Infrastructure (infra/) — Infrastructure Layer: - ORM models (SQLAlchemy) - Repository implementations - Kafka, Redis, external APIs - Unit of Work

API (api/) — Presentation Layer: - gRPC servicers - REST controllers (planned) - Request/Response mapping

Transactional Outbox Pattern

Обеспечивает at-least-once доставку событий в Kafka:

1. API процесс: бизнес-операция + событие сохраняются в одной транзакции
2. Worker процесс: polling из outbox_events → Kafka → маркировка PUBLISHED

Библиотека: libs/python/storage/patterns/omni-box/

Используется в: - Identity service - Credential service

Unit of Work Pattern

Управление транзакциями и координация repositories:

1
2
3
4

async with uow.transaction() as tx:
    user = await tx.users.get_by_id(user_id)
    await tx.users.update(user)
    await tx.outbox.create(event)

Библиотека: libs/python/storage/patterns/unit-of-work-kit/

Repository Pattern

Абстракция доступа к данным: - Protocols в core/[entity]/repositories.py - Implementations в infra/repositories/[entity].py - Возвращают Domain Entities, не ORM модели

Domain Services

Бизнес-логика, не привязанная к конкретной сущности: - UserDomainService (Identity) — валидация username - PasswordDomainService (Credential) — Argon2 hashing, zxcvbn validation

Технологии

Python 3.12+

• Async/await — asyncio, uvloop (только Linux/macOS)
• Type hints — mypy strict mode
• Pydantic 2.x — валидация и serialization

gRPC

• Protocol Buffers — proto/aiops/
• grpcio 1.78+ — runtime
• Health checks — grpc-health-checking
• Reflection — grpc-reflection

PostgreSQL

• SQLAlchemy 2.x — async ORM
• asyncpg — драйвер
• Alembic 1.18+ — миграции
• Partitioning — для outbox_events (по времени)

Kafka

• aiokafka — async producer/consumer
• Transactional Outbox — надежная доставка
• Event schemas — в libs/python/common/service-contracts/

Observability

• structlog — structured logging
• prometheus-client — metrics
• OpenTelemetry — distributed tracing

Разделы

• Backend Overview — обзор backend архитектуры
• Service Patterns — общие паттерны сервисов
• API Guidelines — стандарты API
• Event-Driven Patterns — Transactional Outbox, Event Sourcing
• Database Access Patterns — Repository, UoW
• Caching — Redis caching strategies
• Async Jobs and Workers — APScheduler, outbox workers
• Idempotency — идемпотентность операций
• Error Handling — обработка ошибок
• Backend Testing — unit, integration, e2e тесты

Связанные страницы

Сервисы

• Identity service — пример Clean Architecture
• Credential service — пример Domain Service
• Service Catalog — все сервисы

Архитектура

• Architecture Principles — принципы проектирования
• Data Flow / Event Flow — поток событий
• Reliability and Scalability — надежность

Данные

• Event Schema Catalog — схемы событий Kafka
• Data Contracts — контракты между сервисами

Разработка

• Coding Standards — стандарты кода
• Code Review Guide — code review