docs/architecture.md

# Архитектура

## Общая схема контейнеров

```mermaid
flowchart LR
  user[Пользователь / браузер]
  nginx[nginx\n:80 / :443]

  backend[Backend API\nSymfony 7.3\nphp84:9000]
  cabinet[Cabinet legacy\nSymfony 5.4\nphp82:9000]
  nextjs[Sovamed site\nNext.js\nnextjs:3001]
  static[Static apps\nfrontend/adminPanel/kiosk dist]

  pg[(PostgreSQL\npgsql:5432)]
  redis[(Redis\nredis:6379)]
  bitrix[(Bitrix MySQL)]
  mis[Infoclinica / MIS]
  sms[SMS / Notisend]
  calltouch[Calltouch]

  user --> nginx
  nginx -->|api.sovamed.ru| backend
  nginx -->|cabinet.sovamed.ru| cabinet
  nginx -->|sovamed site| nextjs
  nginx -->|static dist| static

  backend --> pg
  backend --> redis
  backend --> bitrix
  backend --> mis
  backend --> sms
  backend --> calltouch

  cabinet --> pg
  cabinet --> redis
  cabinet --> bitrix
  cabinet --> mis
  cabinet --> sms
  cabinet --> calltouch
```

## Роли сервисов

- `nginx` - публичная точка входа, TLS, маршрутизация на PHP-FPM и статические файлы.
- `php84` - PHP-FPM для `apps/backend`, рабочая директория `/var/www/backend`.
- `php82` - PHP-FPM для `apps/cabinet`, рабочая директория `/var/www/cabinet`.
- `pgsql` - PostgreSQL, данные монтируются в `infrastructure/pgsql/data`.
- `redis` - Redis с обязательным паролем.
- `nodejs` - helper-контейнер для Node-проектов, в текущем compose работает как долгоживущий контейнер без dev-команды.
- `nextjs` - production-контейнер для `apps/sovamed`, но сами исходники `apps/sovamed` в текущем дереве отсутствуют.

## Потоки данных

Backend и cabinet оба работают с медицинскими справочниками, врачами, филиалами, ценами, отзывами и записями. Оба проекта интегрируются с внешними системами:

- Bitrix;
- Infoclinica/MIS;
- Calltouch;
- SMS/уведомления;
- Yandex/Direct в старом cabinet.

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

## Слои приложений

```mermaid
flowchart TB
  http[HTTP request]
  controller[Controller\nмаршруты, request/response]
  dto[DTO / Form\nвалидация входных данных]
  service[Service / Bundle\nбизнес-логика и интеграции]
  repo[Repository\nзапросы Doctrine]
  entity[Entity\nмодель данных]
  db[(PostgreSQL / внешние БД)]
  external[Внешние API]

  http --> controller
  controller --> dto
  controller --> service
  controller --> repo
  service --> repo
  repo --> entity
  repo --> db
  service --> external
```

В `backend` этот слой выражен чище: контроллеры тоньше, логика вынесена в сервисы и DTO, роуты объявлены attributes. В `cabinet` часть логики остается внутри контроллеров и локальных `Bundle/*`-классов, потому что это старый монолит с Twig-страницами и админскими сценариями.

## Поток API-запроса backend

```mermaid
sequenceDiagram
  participant Client as Клиент
  participant Nginx as nginx
  participant PHP as php84
  participant Symfony as Symfony Kernel
  participant Controller as Controller
  participant Service as Service
  participant DB as PostgreSQL
  participant External as Внешний API

  Client->>Nginx: HTTPS запрос api.sovamed.ru
  Nginx->>PHP: FastCGI /public/index.php
  PHP->>Symfony: Request
  Symfony->>Controller: route + DI
  Controller->>Service: бизнес-операция
  Service->>DB: чтение/запись через Repository
  Service->>External: при необходимости MIS/Bitrix/SMS
  External-->>Service: ответ
  DB-->>Service: данные
  Service-->>Controller: результат
  Controller-->>Client: JsonResponse
```

## Поток страницы cabinet

```mermaid
sequenceDiagram
  participant User as Пользователь
  participant Nginx as nginx
  participant PHP as php82
  participant Controller as Symfony Controller
  participant Service as Service/Bundle
  participant Twig as Twig
  participant DB as PostgreSQL

  User->>Nginx: HTTPS запрос cabinet.sovamed.ru
  Nginx->>PHP: FastCGI /public/index.php
  PHP->>Controller: route + security
  Controller->>Service: подготовка данных
  Service->>DB: Doctrine query
  DB-->>Service: сущности/массивы
  Service-->>Controller: результат
  Controller->>Twig: render template
  Twig-->>User: HTML
```

## Где искать код

- HTTP endpoints backend: `apps/backend/src/Controller`.
- HTTP endpoints cabinet: `apps/cabinet/src/Controller`.
- Модели Doctrine: `src/Entity` в каждом приложении.
- Запросы к БД: `src/Repository`.
- Бизнес-логика: `src/Service`.
- Консольные задачи синхронизации: `src/Command`.
- Twig-шаблоны cabinet: `apps/cabinet/templates`.
- Frontend-ассеты cabinet: `apps/cabinet/assets`.

## Следующие страницы

- [Backend: архитектура модулей](./apps/backend-architecture.md)
- [Cabinet: архитектура модулей](./apps/cabinet-architecture.md)
- [Модели данных](./data-model.md)