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

Заявка начинается в кабинете предпринимателя, переходит в Backoffice для проверки и проходит через API до финального решения. Ниже видно, кто отвечает за каждый участок пути, где хранится состояние и как этот контур развёрнут. Диаграммы открываются по отдельности, поэтому каждую связь можно разобрать без перегруженного общего полотна.

Как проходит заявка

От кабинета предпринимателя до работающего контура

Начните с component view, чтобы увидеть границы ответственности, затем проверьте внутренний workflow API, структуру репозитория и реальный deployment в Docker Compose.

Mermaid C4SVG build-timeCustom SVG state machine

01C4 Level 2КомпонентыКто ведёт заявку и принимает решение

Предприниматель начинает заявку в Client Web, сотрудник банка проверяет её в Backoffice Web. API хранит состояние, вызывает scoring и применяет decision engine.

Показать: Маршрут заявки

На узком экране схему можно прокручивать внутри блока.

Схема статична по умолчанию. Маршрут подсвечивается только по кнопке ниже.

1. 01Client Web
2. 02API
3. 03Scoring Service
4. 04Decision engine
5. 05PostgreSQL

service / container database runtime compile-time / generated

Текстовое описание

• Предприниматель работает в Client Web.
• Сотрудник банка работает в Backoffice Web.
• Оба интерфейса обращаются к API по HTTP/JSON.
• API вызывает Scoring Service по POST /v1/score и получает score, recommendation и explainability metadata.
• Полный ответ включает factors, reasons, next actions, explainability и model metadata.
• API принимает доменное решение и пишет заявку, workflow, scoring jobs и audit в PostgreSQL.

02C4 Level 3API внутриКак API проводит заявку через workflow

После HTTP-запроса API проходит guards и command handlers, проверяет переход state machine, ставит scoring job и фиксирует результат.

Показать: Путь решения

На узком экране схему можно прокручивать внутри блока.

Схема статична по умолчанию. Маршрут подсвечивается только по кнопке ниже.

1. 01HTTP boundary
2. 02Guards
3. 03Command handler
4. 04scoring_jobs
5. 05Decision engine
6. 06Audit

service / container database runtime compile-time / generated

Текстовое описание

• HTTP boundary передаёт команду через auth/session guards.
• Command handlers вызывают application workflow и state machine.
• QueueWorkerService забирает запись scoring_jobs внутри API с блокировкой строки PostgreSQL.
• Decision engine учитывает autonomy policy и результат scoring.
• Workflow store сохраняет транзакцию, application events и audit, reports готовят данные для просмотра.

03FlowchartРепозиторийГде живут приложения и контракты

Схема разделяет runtime-приложения, compile-time packages, generated OpenAPI и tooling. docs/prod/site находится за пределами pnpm workspace.

Показать: Поток генерации

На узком экране схему можно прокручивать внутри блока.

Схема статична по умолчанию. Маршрут подсвечивается только по кнопке ниже.

1. 01apps/api
2. 02packages/sdk/openapi.json
3. 03packages/sdk
4. 04Client Web

service / container database runtime compile-time / generated

Текстовое описание

• apps/client, apps/backoffice и apps/api используют shared packages через workspace imports.
• apps/scoring остаётся workspace-приложением без зависимости от packages/*.
• Nest API генерирует OpenAPI-документ, из которого openapi-ts создаёт SDK.
• docs/prod/site не входит в pnpm workspace и хранит свои SVG-артефакты.

04C4 DeploymentРазвёртываниеКак внешний запрос доходит до сервисов

Caddy принимает внешний HTTPS-трафик и направляет его в client, backoffice или API. Внутри Compose API обращается к scoring и PostgreSQL, а monitoring profile проверяет контур.

Показать: Monitoring flow

На узком экране схему можно прокручивать внутри блока.

Схема статична по умолчанию. Маршрут подсвечивается только по кнопке ниже.

1. 01Prometheus
2. 02API /metrics
3. 03blackbox-exporter
4. 04Service /health
5. 05Grafana

service / container database runtime compile-time / generated

Текстовое описание

• Browser actors входят через Caddy на Docker host.
• Caddy маршрутизирует UI к client:3000 и backoffice:3001, API и Swagger к api:4000.
• API обращается к scoring:8000 и postgres:5432.
• Prometheus собирает metrics и probes, Grafana читает Prometheus HTTP API.

Рабочий контур

Ссылки для проверки

Эти адреса ведут в те же части продукта, которые показаны в component и deployment view.

Кабинет предпринимателяsales.eegov.net/loginСоздание заявки и просмотр её текущего состояния.Кабинет сотрудника банкаbackoffice.sales.eegov.net/loginПроверка заявки, запрос сведений и принятие решения.Swagger APIsales.eegov.net/api/docsОперации API, схемы запросов и ответы сервиса.

Что показать на защите

Скрины рабочего контура

Здесь собраны кадры интерфейсов, локальных Compose-запусков, production-сервера и мониторинга.

Web-контур

Инфраструктура

#Как читать набор

#Component overview, C4 Level 2

Этот срез отвечает на вопрос «кто ведёт заявку». Предприниматель создаёт её в Client Web, сотрудник банка проверяет данные в Backoffice Web. Оба интерфейса обращаются к API по HTTP/JSON. API отправляет запрос в Scoring Service через POST /v1/score, получает score, recommendation и объяснение результата, затем применяет decision engine и сохраняет ход заявки в PostgreSQL.

Полный ответ scoring включает factors, reasons, next actions, explainability и model metadata. Docker, порты, volumes и monitoring здесь не показаны: они нужны для deployment view, а не для разделения ответственности компонентов.

#API internals, C4 Level 3

Здесь видно, что происходит после HTTP-запроса. HTTP boundary пропускает команду через auth/session guards, command handlers передают её в application workflow, а state machine проверяет допустимый переход. QueueWorkerService работает внутри API и забирает записи из PostgreSQL scoring_jobs с блокировкой строки. Отдельного брокера и отдельного worker-контейнера нет.

Decision engine сопоставляет результат scoring с autonomy policy. Workflow store выполняет транзакционную запись, application events и audit оставляют историю перехода, а reports готовят данные для просмотра сотрудником банка.

#Repository and package view

Эта схема показывает не сетевой маршрут, а границы кода. apps/client, apps/backoffice и apps/api используют общие contracts, SDK, UI и i18n через workspace imports. apps/scoring тоже входит в workspace, но не импортирует packages/*.

OpenAPI-документ создаётся из контроллеров Nest API в packages/sdk/openapi.json; затем openapi-ts генерирует SDK. packages/contracts содержит общие типы и импортируется приложениями, но не является источником OpenAPI. ESLint, TypeScript config и root tooling обслуживают сборку, а не runtime. docs/prod/site находится вне pnpm workspace и имеет собственные зависимости.

#Deployment view, C4 Deployment

Здесь показан путь внешнего запроса. Браузер приходит на Caddy, Caddy отправляет UI в client или backoffice, а API и Swagger в api. Внутри Compose client и backoffice используют Next rewrite /api/*, API обращается к scoring и PostgreSQL.

Monitoring profile включает Prometheus, Grafana, node-exporter, cAdvisor и blackbox-exporter. Prometheus собирает /metrics API и метрики инфраструктуры, blackbox проверяет client, backoffice, API /health и scoring /health, Grafana читает Prometheus HTTP API. Ниже показаны Grafana, локальные Compose-запуски в Podman и Docker Desktop, а также статусы контейнеров на сервере.

#Ограничения текущего контура

• Redis, RabbitMQ, Kafka, object storage, standalone mocks и отдельный worker не являются текущими сервисами Compose и не показаны.
• API имеет локальный filesystem adapter, но он не используется текущим document workflow. Object storage не развёрнут.
• Старые target-state описания worker и object storage в docs/ARCHITECTURE.md относятся к будущему состоянию и не должны читаться как текущий deployment.
• Диаграмма состояний заявки остаётся custom SVG: её задача показать переходы и роли, а не инфраструктурные границы.

#Сборка диаграмм

Исходники лежат в docs/developers/diagrams/*.mmd, а committed SVG и manifest в docs/developers/diagrams/generated/.

npm run diagrams:build
npm run diagrams:check
npm run build

diagrams:build запускает pinned @mermaid-js/mermaid-cli и обновляет SVG, manifest и TypeScript-индекс. diagrams:check повторяет рендер и сравнивает его с сохранёнными файлами. Эти команды нужны при изменении диаграмм и выполняются в GitHub CI. Сборка Vercel просто собирает Rspress из готовых SVG и индекса, сохранённых в Git.