vigdorov/hotel-analysis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d32e367383e713d574f71ac3cc3f2e701440ab4c
hotel-analysis/C4-Architecture.md

31 KiB
Raw Blame History

Назад

C4 Architecture Diagrams - TaskManager

Содержание

  1. Level 1: System Context
  2. Level 2: Container Diagram
  3. Level 3: Component Diagram - Tasks Service
  4. Level 3: Component Diagram - Adapter Layer

Level 1: System Context

Показывает TaskManager в контексте пользователей и внешних систем.

C4Context
    title System Context diagram for TaskManager

    Person(hotel_staff, "Hotel Staff", "Сотрудники отеля (горничные, техники, менеджеры)")
    Person(admin, "System Admin", "Администратор системы")
    Person(guest, "Hotel Guest", "Гость отеля")

    System(taskmanager, "TaskManager", "Платформа для управления задачами между подразделениями отеля и интеграции с внешними системами")

    System_Ext(pms, "PMS System", "Система управления отелем (Opera, Fidelio)")
    System_Ext(erp, "ERP System", "Система управления ресурсами")
    System_Ext(housekeeping, "Housekeeping App", "Приложение для управления уборкой")
    System_Ext(email, "Email System", "SMTP сервер для отправки email")
    System_Ext(sms, "SMS Gateway", "Сервис отправки SMS (Twilio)")
    System_Ext(telegram, "Telegram", "Telegram Bot API")
    System_Ext(s3, "AWS S3", "Хранилище файлов")

    Rel(hotel_staff, taskmanager, "Создает и управляет задачами", "Web/Mobile")
    Rel(admin, taskmanager, "Настраивает систему, связи, роли", "Web Admin")
    Rel(guest, taskmanager, "Создает запросы на обслуживание", "Telegram Bot")

    Rel(taskmanager, pms, "Получает/отправляет данные о бронированиях, номерах", "REST API/Webhook")
    Rel(taskmanager, erp, "Интегрируется с учетом ресурсов", "REST API")
    Rel(taskmanager, housekeeping, "Отправляет задачи на уборку", "REST API/Push")
    Rel(taskmanager, email, "Отправляет уведомления", "SMTP")
    Rel(taskmanager, sms, "Отправляет SMS уведомления", "REST API")
    Rel(taskmanager, telegram, "Получает запросы гостей, отправляет уведомления", "Webhook/Bot API")
    Rel(taskmanager, s3, "Хранит файлы и фото", "S3 API")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2")

Level 2: Container Diagram

Показывает основные контейнеры (приложения и хранилища данных) внутри TaskManager.

C4Container
    title Container diagram for TaskManager

    Person(hotel_staff, "Hotel Staff", "Сотрудники отеля")
    Person(admin, "System Admin", "Администратор системы")
    Person(guest, "Hotel Guest", "Гость отеля")

    System_Ext(pms, "PMS System", "Opera/Fidelio")
    System_Ext(erp, "ERP System", "ERP")
    System_Ext(housekeeping_ext, "Housekeeping App", "External App")
    System_Ext(email_ext, "Email System", "SMTP")
    System_Ext(sms_ext, "SMS Gateway", "Twilio")
    System_Ext(telegram_ext, "Telegram", "Bot API")
    System_Ext(s3_ext, "AWS S3", "File Storage")

    Container_Boundary(taskmanager, "TaskManager System") {

        Container(web_admin, "Web Admin", "React, TypeScript", "Веб-приложение для настройки системы и управления")
        Container(mobile_app, "Mobile App", "React Native/Flutter", "Мобильное приложение для сотрудников")

        Container(api_gateway, "API Gateway", "Kong/Envoy", "Единая точка входа, маршрутизация, аутентификация")

        Container(tasks_service, "Tasks Service", "Python, FastAPI, gRPC", "Управление задачами")
        Container(connections_service, "Connections Service", "Python, FastAPI, gRPC", "Управление связями между адаптерами")
        Container(users_service, "Users Service", "Python, FastAPI, gRPC", "Управление пользователями")
        Container(permissions_service, "Permissions Service", "Python, FastAPI, gRPC", "Управление ролями и правами (RBAC)")
        Container(notification_service, "Notification Service", "Python, FastAPI", "Отправка уведомлений через разные каналы")
        Container(file_storage_service, "File Storage Service", "Python, FastAPI", "Управление файлами")
        Container(audit_service, "Audit Service", "Python, FastAPI", "Логирование всех действий")
        Container(scheduler_service, "Scheduler Service", "Python, FastAPI", "Управление периодическими задачами")
        Container(events_service, "Events Service", "Python, FastAPI, gRPC", "Управление мероприятиями")

        Container(pms_adapter, "PMS Adapter", "Python", "Адаптер для PMS системы")
        Container(erp_adapter, "ERP Adapter", "Python", "Адаптер для ERP системы")
        Container(housekeeping_adapter, "Housekeeping Adapter", "Python", "Адаптер для приложения уборки")
        Container(telegram_adapter, "Telegram Bot Adapter", "Python", "Адаптер для Telegram бота")

        ContainerQueue(kafka, "Message Broker", "Apache Kafka", "Асинхронная коммуникация между сервисами")

        ContainerDb(postgres, "Database", "PostgreSQL", "Хранение данных системы")
        ContainerDb(redis, "Cache", "Redis", "Кэширование данных, сессии")
    }

    Rel(hotel_staff, web_admin, "Использует", "HTTPS")
    Rel(hotel_staff, mobile_app, "Использует", "HTTPS")
    Rel(admin, web_admin, "Настраивает систему", "HTTPS")
    Rel(guest, telegram_adapter, "Отправляет запросы", "Telegram")

    Rel(web_admin, api_gateway, "Делает API запросы", "REST/gRPC-Web")
    Rel(mobile_app, api_gateway, "Делает API запросы", "REST/gRPC")

    Rel(api_gateway, tasks_service, "Маршрутизирует запросы", "gRPC")
    Rel(api_gateway, users_service, "Маршрутизирует запросы", "gRPC")
    Rel(api_gateway, connections_service, "Маршрутизирует запросы", "gRPC")
    Rel(api_gateway, events_service, "Маршрутизирует запросы", "gRPC")
    Rel(api_gateway, file_storage_service, "Маршрутизирует запросы", "REST")

    Rel(tasks_service, kafka, "Публикует события", "Kafka Protocol")
    Rel(connections_service, kafka, "Публикует/читает события", "Kafka Protocol")
    Rel(scheduler_service, kafka, "Публикует триггеры", "Kafka Protocol")
    Rel(events_service, kafka, "Публикует события", "Kafka Protocol")
    Rel(notification_service, kafka, "Читает события", "Kafka Protocol")
    Rel(audit_service, kafka, "Читает все события", "Kafka Protocol")

    Rel(tasks_service, permissions_service, "Проверяет права", "gRPC")
    Rel(users_service, permissions_service, "Проверяет права", "gRPC")

    Rel(pms_adapter, kafka, "Публикует сообщения", "Kafka Protocol")
    Rel(erp_adapter, kafka, "Публикует сообщения", "Kafka Protocol")
    Rel(housekeeping_adapter, kafka, "Публикует сообщения", "Kafka Protocol")
    Rel(telegram_adapter, kafka, "Публикует сообщения", "Kafka Protocol")

    Rel(pms_adapter, pms, "Получает/отправляет данные", "REST API/Webhook")
    Rel(erp_adapter, erp, "Получает/отправляет данные", "REST API")
    Rel(housekeeping_adapter, housekeeping_ext, "Отправляет задачи", "REST API/Push")
    Rel(telegram_adapter, telegram_ext, "Взаимодействует с ботом", "Webhook/Bot API")

    Rel(notification_service, email_ext, "Отправляет email", "SMTP")
    Rel(notification_service, sms_ext, "Отправляет SMS", "REST API")
    Rel(notification_service, telegram_ext, "Отправляет сообщения", "Bot API")

    Rel(file_storage_service, s3_ext, "Хранит файлы", "S3 API")

    Rel(tasks_service, postgres, "Читает/пишет данные", "SQL")
    Rel(users_service, postgres, "Читает/пишет данные", "SQL")
    Rel(connections_service, postgres, "Читает/пишет данные", "SQL")
    Rel(permissions_service, postgres, "Читает/пишет данные", "SQL")
    Rel(scheduler_service, postgres, "Читает/пишет данные", "SQL")
    Rel(events_service, postgres, "Читает/пишет данные", "SQL")
    Rel(audit_service, postgres, "Пишет логи", "SQL")
    Rel(file_storage_service, postgres, "Пишет метаданные", "SQL")

    Rel(tasks_service, redis, "Кэширует данные", "Redis Protocol")
    Rel(users_service, redis, "Кэширует данные", "Redis Protocol")
    Rel(permissions_service, redis, "Кэширует права", "Redis Protocol")

    UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="2")

Level 3: Component Diagram - Tasks Service

Показывает внутреннюю структуру Tasks Service.

C4Component
    title Component diagram for Tasks Service

    Container_Ext(api_gateway, "API Gateway", "Kong/Envoy", "Точка входа")
    Container_Ext(kafka, "Kafka", "Apache Kafka", "Message Broker")
    ContainerDb_Ext(postgres, "PostgreSQL", "Database", "Основная БД")
    ContainerDb_Ext(redis, "Redis", "Cache", "Кэш")
    Container_Ext(permissions_service, "Permissions Service", "Python, gRPC", "Проверка прав")
    Container_Ext(file_storage_service, "File Storage Service", "Python", "Управление файлами")

    Container_Boundary(tasks_service, "Tasks Service") {

        Component(grpc_api, "gRPC API", "Python, gRPC", "Обработка gRPC запросов")
        Component(rest_api, "REST API", "FastAPI", "Обработка REST запросов (fallback)")

        Component(task_controller, "Task Controller", "Python", "Обработка бизнес-логики задач")
        Component(status_controller, "Status Controller", "Python", "Управление статусами задач")
        Component(dependency_controller, "Dependency Controller", "Python", "Управление зависимостями")
        Component(history_controller, "History Controller", "Python", "Управление историей изменений")

        Component(task_repository, "Task Repository", "SQLAlchemy", "Работа с БД задач")
        Component(status_repository, "Status Repository", "SQLAlchemy", "Работа с БД статусов")
        Component(dependency_repository, "Dependency Repository", "SQLAlchemy", "Работа с БД зависимостей")
        Component(history_repository, "History Repository", "SQLAlchemy", "Работа с БД истории")

        Component(kafka_producer, "Kafka Producer", "aiokafka", "Публикация событий в Kafka")
        Component(kafka_consumer, "Kafka Consumer", "aiokafka", "Чтение событий из Kafka")

        Component(cache_manager, "Cache Manager", "Redis Client", "Управление кэшем")
        Component(permission_client, "Permission Client", "gRPC Client", "Проверка прав доступа")

        Component(task_validator, "Task Validator", "Pydantic", "Валидация данных задач")
        Component(event_mapper, "Event Mapper", "Python", "Маппинг событий")
    }

    Rel(api_gateway, grpc_api, "Отправляет gRPC запросы", "gRPC")
    Rel(api_gateway, rest_api, "Отправляет REST запросы", "HTTP/JSON")

    Rel(grpc_api, task_controller, "Вызывает методы")
    Rel(rest_api, task_controller, "Вызывает методы")

    Rel(task_controller, task_validator, "Валидирует данные")
    Rel(task_controller, permission_client, "Проверяет права")
    Rel(task_controller, task_repository, "Работает с задачами")
    Rel(task_controller, status_controller, "Изменяет статусы")
    Rel(task_controller, dependency_controller, "Управляет зависимостями")
    Rel(task_controller, history_controller, "Записывает историю")
    Rel(task_controller, cache_manager, "Кэширует данные")
    Rel(task_controller, kafka_producer, "Публикует события")

    Rel(status_controller, status_repository, "Работает со статусами")
    Rel(dependency_controller, dependency_repository, "Работает с зависимостями")
    Rel(history_controller, history_repository, "Работает с историей")

    Rel(kafka_consumer, event_mapper, "Маппит события")
    Rel(event_mapper, task_controller, "Обрабатывает события")

    Rel(task_repository, postgres, "Выполняет SQL запросы", "SQL")
    Rel(status_repository, postgres, "Выполняет SQL запросы", "SQL")
    Rel(dependency_repository, postgres, "Выполняет SQL запросы", "SQL")
    Rel(history_repository, postgres, "Выполняет SQL запросы", "SQL")

    Rel(cache_manager, redis, "Кэширует/читает данные", "Redis Protocol")
    Rel(permission_client, permissions_service, "Проверяет права", "gRPC")

    Rel(kafka_producer, kafka, "Публикует события", "Kafka Protocol")
    Rel(kafka_consumer, kafka, "Читает события", "Kafka Protocol")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Level 3: Component Diagram - Adapter Layer

Показывает внутреннюю структуру адаптера (на примере PMS Adapter).

C4Component
    title Component diagram for PMS Adapter (Example)

    System_Ext(pms_system, "PMS System", "Opera/Fidelio", "Внешняя PMS система")
    Container_Ext(kafka, "Kafka", "Apache Kafka", "Message Broker")
    Container_Ext(postgres, "PostgreSQL", "Database", "Хранение состояния адаптера")

    Container_Boundary(pms_adapter, "PMS Adapter") {

        Component(webhook_handler, "Webhook Handler", "FastAPI", "Принимает webhook от PMS")
        Component(api_poller, "API Poller", "Python, APScheduler", "Опрашивает PMS API по расписанию")
        Component(rest_client, "REST Client", "httpx", "HTTP клиент для PMS API")

        Component(inbound_transformer, "Inbound Transformer", "Python", "PMS формат → Стандартный формат")
        Component(outbound_transformer, "Outbound Transformer", "Python", "Стандартный формат → PMS формат")

        Component(message_validator, "Message Validator", "Pydantic", "Валидация сообщений")
        Component(event_publisher, "Event Publisher", "aiokafka", "Публикация событий в Kafka")
        Component(event_consumer, "Event Consumer", "aiokafka", "Чтение событий из Kafka")

        Component(state_manager, "State Manager", "SQLAlchemy", "Управление состоянием синхронизации")
        Component(error_handler, "Error Handler", "Python", "Обработка ошибок и retry")
        Component(config_manager, "Config Manager", "Python", "Управление конфигурацией")
    }

    Rel(pms_system, webhook_handler, "Отправляет webhook", "HTTP/JSON")
    Rel(api_poller, rest_client, "Запрашивает данные")
    Rel(rest_client, pms_system, "Делает API запросы", "REST/SOAP")

    Rel(webhook_handler, inbound_transformer, "Передает данные")
    Rel(api_poller, inbound_transformer, "Передает данные")

    Rel(inbound_transformer, message_validator, "Валидирует сообщение")
    Rel(message_validator, event_publisher, "Публикует валидное событие")

    Rel(event_consumer, kafka, "Читает исходящие события", "Kafka Protocol")
    Rel(event_consumer, outbound_transformer, "Передает событие")
    Rel(outbound_transformer, rest_client, "Отправляет в PMS")

    Rel(event_publisher, kafka, "Публикует входящие события", "Kafka Protocol")

    Rel(state_manager, postgres, "Сохраняет состояние", "SQL")
    Rel(error_handler, state_manager, "Логирует ошибки")

    Rel(webhook_handler, error_handler, "Обрабатывает ошибки")
    Rel(api_poller, error_handler, "Обрабатывает ошибки")
    Rel(rest_client, error_handler, "Обрабатывает ошибки")

    Rel(config_manager, api_poller, "Предоставляет конфигурацию")
    Rel(config_manager, rest_client, "Предоставляет конфигурацию")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Deployment Diagram (Kubernetes)

Показывает развертывание в Kubernetes кластере.

C4Deployment
    title Deployment Diagram for TaskManager (Kubernetes)

    Deployment_Node(k8s_cluster, "Kubernetes Cluster", "GKE/EKS/AKS") {

        Deployment_Node(ingress_ns, "Namespace: ingress") {
            Container(ingress, "Ingress Controller", "NGINX/Traefik", "Входная точка для внешнего трафика")
        }

        Deployment_Node(gateway_ns, "Namespace: gateway") {
            Container(api_gateway, "API Gateway", "Kong/Envoy", "3 replicas", "Маршрутизация и аутентификация")
        }

        Deployment_Node(services_ns, "Namespace: services") {
            Container(tasks_svc, "Tasks Service", "Python, FastAPI", "5 replicas", "Управление задачами")
            Container(users_svc, "Users Service", "Python, FastAPI", "3 replicas", "Управление пользователями")
            Container(connections_svc, "Connections Service", "Python, FastAPI", "2 replicas", "Управление связями")
            Container(permissions_svc, "Permissions Service", "Python, FastAPI", "3 replicas", "RBAC")
            Container(notification_svc, "Notification Service", "Python, FastAPI", "3 replicas", "Уведомления")
            Container(file_storage_svc, "File Storage Service", "Python, FastAPI", "2 replicas", "Файлы")
            Container(audit_svc, "Audit Service", "Python, FastAPI", "2 replicas", "Аудит")
            Container(scheduler_svc, "Scheduler Service", "Python, FastAPI", "1 replica", "Планировщик")
            Container(events_svc, "Events Service", "Python, FastAPI", "2 replicas", "Мероприятия")
        }

        Deployment_Node(adapters_ns, "Namespace: adapters") {
            Container(pms_adapter, "PMS Adapter", "Python", "2 replicas", "PMS интеграция")
            Container(erp_adapter, "ERP Adapter", "Python", "1 replica", "ERP интеграция")
            Container(housekeeping_adapter, "Housekeeping Adapter", "Python", "2 replicas", "Уборка")
            Container(telegram_adapter, "Telegram Adapter", "Python", "2 replicas", "Telegram бот")
        }

        Deployment_Node(data_ns, "Namespace: data") {
            ContainerDb(postgres_primary, "PostgreSQL Primary", "PostgreSQL 15", "1 pod", "Основная БД (master)")
            ContainerDb(postgres_replica, "PostgreSQL Replica", "PostgreSQL 15", "2 pods", "Реплики для чтения")
            ContainerDb(redis_cluster, "Redis Cluster", "Redis 7", "3 pods", "Кэш и сессии")
            ContainerQueue(kafka_cluster, "Kafka Cluster", "Apache Kafka", "3 brokers", "Message broker")
        }

        Deployment_Node(monitoring_ns, "Namespace: monitoring") {
            Container(prometheus, "Prometheus", "Prometheus", "Сбор метрик")
            Container(grafana, "Grafana", "Grafana", "Визуализация метрик")
            Container(jaeger, "Jaeger", "Jaeger", "Distributed tracing")
        }
    }

    Deployment_Node(external_services, "External Services") {
        Container(s3, "AWS S3", "Object Storage", "Хранилище файлов")
        Container(smtp, "SMTP Server", "Email", "Отправка email")
        Container(sms_gateway, "SMS Gateway", "Twilio", "Отправка SMS")
    }

    Rel(ingress, api_gateway, "Routes traffic", "HTTPS")

    Rel(api_gateway, tasks_svc, "Calls", "gRPC")
    Rel(api_gateway, users_svc, "Calls", "gRPC")
    Rel(api_gateway, connections_svc, "Calls", "gRPC")
    Rel(api_gateway, events_svc, "Calls", "gRPC")
    Rel(api_gateway, file_storage_svc, "Calls", "REST")

    Rel(tasks_svc, kafka_cluster, "Publishes/Consumes", "Kafka Protocol")
    Rel(connections_svc, kafka_cluster, "Publishes/Consumes", "Kafka Protocol")
    Rel(scheduler_svc, kafka_cluster, "Publishes", "Kafka Protocol")
    Rel(notification_svc, kafka_cluster, "Consumes", "Kafka Protocol")
    Rel(audit_svc, kafka_cluster, "Consumes", "Kafka Protocol")

    Rel(pms_adapter, kafka_cluster, "Publishes/Consumes", "Kafka Protocol")
    Rel(erp_adapter, kafka_cluster, "Publishes/Consumes", "Kafka Protocol")
    Rel(housekeeping_adapter, kafka_cluster, "Publishes/Consumes", "Kafka Protocol")
    Rel(telegram_adapter, kafka_cluster, "Publishes/Consumes", "Kafka Protocol")

    Rel(tasks_svc, postgres_primary, "Writes", "SQL")
    Rel(tasks_svc, postgres_replica, "Reads", "SQL")
    Rel(users_svc, postgres_primary, "Writes", "SQL")
    Rel(users_svc, postgres_replica, "Reads", "SQL")
    Rel(audit_svc, postgres_primary, "Writes logs", "SQL")

    Rel(tasks_svc, redis_cluster, "Cache", "Redis Protocol")
    Rel(users_svc, redis_cluster, "Cache", "Redis Protocol")
    Rel(permissions_svc, redis_cluster, "Cache permissions", "Redis Protocol")

    Rel(file_storage_svc, s3, "Stores files", "S3 API")
    Rel(notification_svc, smtp, "Sends emails", "SMTP")
    Rel(notification_svc, sms_gateway, "Sends SMS", "REST API")

    Rel(prometheus, tasks_svc, "Scrapes metrics", "HTTP")
    Rel(prometheus, users_svc, "Scrapes metrics", "HTTP")
    Rel(grafana, prometheus, "Queries metrics", "HTTP")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Sequence Diagram: Creating Task from External System

Показывает последовательность действий при создании задачи из внешней системы.

sequenceDiagram
    participant PMS as PMS System (Opera)
    participant Adapter as PMS Adapter
    participant Kafka as Apache Kafka
    participant Connections as Connections Service
    participant Tasks as Tasks Service
    participant Permissions as Permissions Service
    participant Audit as Audit Service
    participant Notification as Notification Service
    participant DB as PostgreSQL
    participant Housekeeping as Housekeeping Adapter
    participant HK_App as Housekeeping App

    Note over PMS,HK_App: Сценарий: Гость выехал из номера, нужна уборка

    PMS->>Adapter: Webhook: Guest Checkout (Room 305)
    Adapter->>Adapter: Validate webhook signature
    Adapter->>Adapter: Transform to standard format
    Adapter->>Kafka: Publish: adapters.pms.checkout

    Note over Kafka: Topic: adapters.pms.checkout

    Kafka->>Connections: Consume: adapters.pms.checkout
    Connections->>DB: Get routing rules for PMS → TaskManager
    DB-->>Connections: Routing rules
    Connections->>Connections: Apply rules: checkout → create cleaning task
    Connections->>Kafka: Publish: connections.route_task

    Note over Kafka: Topic: connections.route_task

    Kafka->>Tasks: Consume: connections.route_task
    Tasks->>Permissions: CheckPermission(source_adapter, create_task)
    Permissions->>DB: Query permissions
    DB-->>Permissions: Permission granted
    Permissions-->>Tasks: Allowed

    Tasks->>Tasks: Create task object
    Tasks->>DB: INSERT INTO tasks (...)
    DB-->>Tasks: Task created (id: uuid)

    Tasks->>Kafka: Publish: tasks.created

    Note over Kafka: Topic: tasks.created

    par Parallel Processing
        Kafka->>Audit: Consume: tasks.created
        Audit->>DB: INSERT INTO audit_log

        Kafka->>Notification: Consume: tasks.created
        Notification->>DB: Get user notification preferences
        DB-->>Notification: User prefers Telegram
        Notification->>Notification: Send Telegram notification

        Kafka->>Connections: Consume: tasks.created
        Connections->>DB: Get routing rules for TaskManager → Housekeeping
        DB-->>Connections: Route to Housekeeping Adapter
        Connections->>Kafka: Publish: connections.route_task
    end

    Note over Kafka: Topic: connections.route_task

    Kafka->>Housekeeping: Consume: connections.route_task
    Housekeeping->>Housekeeping: Transform to Housekeeping App format
    Housekeeping->>HK_App: POST /api/tasks (Room 305 cleaning)
    HK_App-->>Housekeeping: Task assigned (assignee: Maria)

    Housekeeping->>Kafka: Publish: adapters.housekeeping.task_assigned

    Kafka->>Tasks: Consume: adapters.housekeeping.task_assigned
    Tasks->>DB: UPDATE tasks SET assignee_id = ...
    Tasks->>Kafka: Publish: tasks.assigned

    Note over PMS,HK_App: Task created and assigned to housekeeping staff

Sequence Diagram: Creating Event with Auto-Generated Tasks

Показывает создание мероприятия и автоматическую генерацию задач.

sequenceDiagram
    participant User as Sales Manager
    participant Web as Web Admin
    participant Gateway as API Gateway
    participant Events as Events Service
    participant Tasks as Tasks Service
    participant Kafka as Apache Kafka
    participant DB as PostgreSQL
    participant Notification as Notification Service

    Note over User,Notification: Сценарий: Создание конференции на 50 человек

    User->>Web: Create Event: "Marketing Conference"
    Web->>Gateway: POST /api/v1/events (event details)
    Gateway->>Gateway: Authenticate & Authorize

    Gateway->>Events: CreateEvent(gRPC)
    Events->>DB: INSERT INTO events
    DB-->>Events: Event created (id: uuid)

    Events->>Events: Generate tasks from event template
    Note over Events: Tasks: Setup chairs, Prepare projector,<br/>Organize coffee break, etc.

    loop For each generated task
        Events->>Tasks: CreateTask(gRPC)
        Tasks->>DB: INSERT INTO tasks
        DB-->>Tasks: Task created
        Tasks->>Kafka: Publish: tasks.created
        Tasks-->>Events: Task ID
    end

    Events->>DB: INSERT INTO event_tasks (event_id, task_id)
    Events->>Kafka: Publish: events.created
    Events->>Kafka: Publish: events.tasks_generated

    Events-->>Gateway: Event + generated tasks
    Gateway-->>Web: 201 Created (event + tasks)
    Web-->>User: Show created event with tasks

    par Notify departments
        Kafka->>Notification: Consume: tasks.created
        loop For each task
            Notification->>Notification: Get assignee notification prefs
            Notification->>Notification: Send notification (Telegram/Email)
        end
    end

    Note over User,Notification: All tasks created and departments notified

Data Flow Diagram

Показывает потоки данных в системе.

flowchart TB
    subgraph External["External Systems"]
        PMS["PMS System"]
        ERP["ERP System"]
        Guest["Guest (Telegram)"]
    end

    subgraph Adapters["Adapter Layer"]
        PMS_A["PMS Adapter"]
        ERP_A["ERP Adapter"]
        TG_A["Telegram Adapter"]
    end

    subgraph Kafka["Apache Kafka"]
        T1["adapters.*"]
        T2["tasks.*"]
        T3["connections.*"]
        T4["notifications.*"]
        T5["audit.*"]
    end

    subgraph Core["Core Services"]
        Connections["Connections Service<br/>(Routing Rules)"]
        Tasks["Tasks Service<br/>(Task Management)"]
        Users["Users Service"]
        Permissions["Permissions Service"]
    end

    subgraph Support["Support Services"]
        Notification["Notification Service"]
        Audit["Audit Service"]
        Scheduler["Scheduler Service"]
    end

    subgraph Data["Data Layer"]
        DB["PostgreSQL"]
        Cache["Redis"]
    end

    %% External to Adapters
    PMS -->|"Webhook/API"| PMS_A
    ERP -->|"API"| ERP_A
    Guest -->|"Telegram Bot"| TG_A

    %% Adapters to Kafka
    PMS_A -->|"Publish events"| T1
    ERP_A -->|"Publish events"| T1
    TG_A -->|"Publish events"| T1

    %% Kafka to Connections
    T1 -->|"Consume"| Connections

    %% Connections routing
    Connections -->|"Route messages"| T3
    T3 -->|"Consume"| Tasks

    %% Tasks operations
    Tasks -->|"Publish events"| T2
    Tasks -->|"Query permissions"| Permissions
    Tasks -->|"Write/Read"| DB
    Tasks -->|"Cache"| Cache

    %% Support services
    T2 -->|"Consume"| Notification
    T2 -->|"Consume"| Audit
    Scheduler -->|"Trigger tasks"| T2

    Notification -->|"Send notifications"| External
    Audit -->|"Write logs"| DB

    %% Users and Permissions
    Users -->|"Write/Read"| DB
    Permissions -->|"Write/Read"| DB
    Permissions -->|"Cache permissions"| Cache

    style Kafka fill:#ff9900
    style Core fill:#00cc66
    style Support fill:#3399ff
    style Data fill:#cc66ff

Notes

Как использовать эти диаграммы:

  1. System Context (Level 1): Показывает TaskManager как черный ящик в контексте пользователей и внешних систем. Используйте для презентации бизнес-заказчикам.

  2. Container Diagram (Level 2): Показывает основные приложения и хранилища данных. Используйте для обсуждения с архитекторами и DevOps командой.

  3. Component Diagrams (Level 3): Показывают внутреннюю структуру отдельных сервисов. Используйте для разработчиков при проектировании конкретного сервиса.

  4. Deployment Diagram: Показывает как система развернута в Kubernetes. Используйте для DevOps и планирования инфраструктуры.

  5. Sequence Diagrams: Показывают взаимодействие компонентов во времени для конкретных сценариев. Используйте для понимания бизнес-процессов.