Payment Orchestrator

Тема

10.01 Network And Runtime Architecture ​

Статус: черновик для обсуждения

1. Назначение документа ​

Этот документ фиксирует текущую network / runtime architecture diagram для Spinbillz / HUB v3.0.0 и объясняет, как она относится к MVP product requirements.

Документ не заменяет application architecture design.

Network diagram показывает:

  • внешние actors;
  • cloud/network zones;
  • entry points;
  • runtime services;
  • managed infrastructure;
  • observability components.

Application architecture отдельно должна описать:

  • domain modules;
  • service responsibilities;
  • event flows;
  • commands/events;
  • data ownership;
  • database schema;
  • transaction processing lifecycle;
  • failure/retry behavior.

2. Source diagram ​

Исходная диаграмма:

Spinbillz v3.0.0 Network Diagram

Файл диаграммы в документации:

text
product-docs-ru/10-technical-architecture/assets/spinbillz-version-3.0.0-network-diagram.png

3. Что показывает диаграмма ​

Диаграмма показывает infrastructure layout в Google Cloud Platform.

Основные зоны:

  • Public zone;
  • Google Cloud Platform;
  • Region europe-north1;
  • Edge / DMZ Zone;
  • VPC / Private Network Zone;
  • Private GKE Cluster;
  • Public-Facing Application Zone;
  • Private Application Zone;
  • Data Services Zone;
  • Observability Zone;
  • Managed Messaging Zone;
  • Managed Storage Zone.

Основные external actors:

  • Customer;
  • Merchant;
  • Backoffice user;
  • Provider.

Основные external/security entry points:

  • Cloudflare WAF;
  • External HTTPS Load Balancer;
  • GKE Gateway API.

4. Public-facing application services ​

Диаграмма содержит следующие public-facing services inside GKE:

  • Forms Service;
  • Merchant Gateway;
  • Backoffice Gateway;
  • Provider Gateway.

Forms Service ​

Forms Service отвечает за customer-facing hosted payment form.

В контексте MVP он связан с:

  • hosted payment URL;
  • payment session token inside URL;
  • polling transaction/session state;
  • dynamic customer fields;
  • redirect to provider URL;
  • customer-facing error/expired state.

Forms Service не должен содержать core business routing logic.

Merchant Gateway ​

Merchant Gateway является entry point для merchant API.

В контексте MVP он связан с:

  • POST /api/v2/deposit;
  • request authentication/signature validation;
  • basic request validation;
  • accepting merchant request even if core service is restarting/lagging;
  • publishing accepted request into async processing pipeline.

Merchant Gateway должен быть thin gateway.

Он не должен содержать full domain logic routing / velocity / fees.

Backoffice Gateway ​

Backoffice Gateway является entry point для Back Office application/API.

В контексте MVP он связан с:

  • platform section;
  • merchant section;
  • users/roles/permissions;
  • merchant/brand/payment method configuration;
  • routing blueprint editor;
  • transaction details/timeline;
  • audit logs;
  • manual correction;
  • webhook resend.

Backoffice Gateway может быть частью Back Office runtime boundary, но domain decisions должны оставаться в core application/domain layer.

Provider Gateway ​

Provider Gateway является public entry point для provider callbacks.

В контексте MVP он связан с:

  • opaque provider callback endpoints;
  • hiding real provider names from public URLs / Swagger surfaces;
  • fast callback acceptance;
  • storing raw callback payload;
  • publishing callback into queue for async processing.

Provider Gateway не должен выполнять full callback processing synchronously.

5. Private application services ​

Диаграмма содержит private application zone:

  • Payment Service;
  • Exchange Service;
  • Report Service.

Payment Service ​

Payment Service должен быть core business application для payment processing.

В контексте MVP Payment Service является основным кандидатом на modular monolith with DDD modules.

Payment Service должен содержать domain modules:

  • Merchant / Brand;
  • Payment Method / MID;
  • Routing;
  • MASTER MID / MASTER MID GROUP;
  • SUB MID / SUB MID GROUP / SUB MID AGGREGATOR;
  • Velocity;
  • FX / Fees;
  • Transaction Lifecycle;
  • Provider Integration;
  • Provider Callback Processing;
  • Merchant Webhooks;
  • Error Mapping;
  • Audit Log;
  • Timeline;
  • Permissions/Visibility, если authorization реализуется на domain/application level.

Payment Service должен обрабатывать events from gateways через messaging.

Exchange Service ​

Exchange Service отвечает за currency rates / currency conversion support.

В контексте MVP он связан с:

  • base currency EUR;
  • conversion from original transaction currency to EUR;
  • conversion from EUR to target/provider currency when needed;
  • FX rate storage/lookup;
  • conversion fee calculation support.

На диаграмме Exchange Service отмечен как Kubernetes CronJobs + Redis/NAT.

Development team должна определить, является ли Exchange Service отдельным service или module/job внутри Payment Service runtime.

Product requirement: FX/conversion behavior должен быть consistent and auditable.

Report Service ​

Report Service отвечает за reports/export generation.

В контексте MVP он связан с:

  • CSV export by current filters;
  • report generation;
  • Cloud Storage for generated reports, если report generation async.

Advanced reports не входят в MVP.

Report Service не должен быть on critical transaction creation path.

6. Managed infrastructure ​

Pub/Sub ​

Диаграмма использует managed messaging zone with Pub/Sub.

В контексте MVP Pub/Sub должен поддерживать async processing для:

  • merchant deposit requests accepted by Merchant Gateway;
  • provider callbacks accepted by Provider Gateway;
  • transaction processing events;
  • merchant webhook dispatch;
  • retry events;
  • report generation events, если needed.

Exact topics/subscriptions должны быть описаны в application architecture / technical design.

PostgreSQL / PgBouncer / Read Replica ​

Диаграмма показывает:

  • PgBouncer;
  • PostgreSQL Primary;
  • PostgreSQL Read Replica.

В контексте MVP PostgreSQL является primary system of record для:

  • merchants;
  • brands;
  • users/roles/permissions;
  • payment method configurations;
  • routing versions;
  • MASTER MID / SUB MID configuration;
  • transactions;
  • timeline events;
  • audit logs;
  • webhook delivery attempts;
  • provider callback records;
  • migration legacy transaction records.

Read replica может использоваться для read-heavy Back Office views / exports, если development team решит это технически полезно.

Redis / Cache ​

Диаграмма содержит Redis cache.

В контексте MVP Redis может использоваться для:

  • gateway/session cache;
  • hosted payment session cache;
  • velocity counters, если development team выберет Redis для high-traffic counters;
  • temporary locks for configuration draft editing;
  • short-lived state.

Critical state не должен существовать только в Redis без durable source of truth.

Cloud Storage ​

Диаграмма содержит Cloud Storage for Reports.

В контексте MVP Cloud Storage может использоваться для:

  • generated CSV exports;
  • temporary report files;
  • signed/internal access to report files, если такой подход будет выбран.

Reports in Cloud Storage не должны раскрывать secret values.

Cloud NAT ​

Cloud NAT используется для outbound traffic из private network.

В контексте MVP outbound traffic нужен для:

  • provider API calls;
  • provider redirect/API integrations;
  • exchange rate source, если Exchange Service получает rates externally;
  • outbound webhook calls to merchant, если architecture route требует NAT.

Provider integrations должны учитывать provider allowlist/IP requirements.

7. Observability ​

Диаграмма содержит Observability Zone:

  • Cloud Logging;
  • Cloud Monitoring;
  • Grafana Stack.

В контексте MVP observability должна покрывать:

  • gateway request rate/errors;
  • transaction creation success/fail;
  • routing outcomes;
  • provider request success/fail/timeout;
  • provider callback acceptance/processing;
  • merchant webhook delivery/retry/exhausted;
  • queue depth/lag;
  • database errors/latency;
  • success rate by provider/merchant/system;
  • suspicious callbacks;
  • secret leakage prevention in logs.

Prometheus/Grafana/internal ops scope описывается отдельно в monitoring document.

8. Как диаграмма соответствует product requirements ​

Диаграмма поддерживает несколько ключевых product decisions:

  • entry points отделены от core processing;
  • Merchant Gateway и Provider Gateway могут продолжать принимать requests/callbacks при restart/lag core service;
  • async messaging через Pub/Sub позволяет decouple gateways and core;
  • Payment Service на diagram соответствует core service, final application name: Orchestrator Service;
  • core service является modular monolith;
  • Forms Service отделяет customer-facing hosted payment form от processing;
  • Report Service не находится на critical transaction path;
  • Observability вынесена отдельно;
  • PostgreSQL является durable system of record;
  • Redis используется как supporting/cache layer;
  • provider outbound traffic проходит controlled network path.

9. Что диаграмма не описывает ​

Диаграмма не отвечает на следующие вопросы:

  • какие exact domain modules находятся внутри Orchestrator Service;
  • какие commands/events используются;
  • какие Pub/Sub topics/subscriptions нужны;
  • как реализован outbox/inbox pattern;
  • как обеспечивается idempotency processing;
  • как именно routing engine выбирает path;
  • где живет authorization/permissions enforcement;
  • где хранится audit log;
  • как versioned configuration применяется к runtime transactions;
  • как устроены database tables;
  • как выполняются migrations;
  • как реализуется secret encryption;
  • как обеспечивается zero-downtime deploy;
  • какие SLO/SLA numbers считаются acceptance;
  • какие services scale independently;
  • какие exact retry policies используются.

Эти вопросы должны быть покрыты отдельным technical design.

10. Product-level architecture constraints ​

Для MVP должны сохраняться следующие constraints:

  • minimal number of services;
  • core business logic inside Orchestrator Service modular monolith;
  • gateways thin and resilient;
  • Merchant Gateway should create payment session and hosted payment URL before returning success;
  • Provider Gateway should publish callback to durable queue before returning OK;
  • no provider names in public provider callback URLs;
  • no secret values in logs/audit/export/API responses;
  • no synchronous dependency on core service for accepting provider callbacks;
  • no synchronous dependency on core service for accepting merchant deposit requests, если gateway accepted request mode используется;
  • merchant-facing entry points should remain available during internal restart/lag;
  • report generation should not affect transaction creation;
  • monitoring/metrics must be available from MVP.

11. Required follow-up architecture documents ​

На основе этой network diagram нужно подготовить следующие technical documents:

  1. Application service responsibilities.
  2. Orchestrator Service modular monolith module map.
  3. Async event flow / Pub/Sub topics.
  4. Deposit creation sequence.
  5. Provider callback sequence.
  6. Merchant webhook delivery sequence.
  7. Database schema draft.
  8. Outbox/inbox and idempotency strategy.
  9. Secrets encryption/storage strategy.
  10. Deployment/scaling strategy.
  11. Resilience strategy for gateway/core restart.

12. Acceptance Criteria ​

Network and Runtime Architecture считается зафиксированной для MVP, если:

  • Диаграмма сохранена внутри product docs.
  • Public actors описаны.
  • Entry points описаны.
  • Public-facing application services описаны.
  • Private application services описаны.
  • Managed infrastructure components описаны.
  • Observability components описаны.
  • Ясно, что diagram label Payment Service соответствует Orchestrator Service.
  • Ясно, что Orchestrator Service является core modular monolith candidate.
  • Ясно, что gateways должны быть thin and async-oriented.
  • Ясно, что diagram не заменяет application architecture design.
  • Follow-up technical architecture documents перечислены.

13. Open Questions ​

Product open questions отсутствуют.

Product decision:

  1. Product / Project: Payment Orchestrator / HUB v3.
  2. Repository: payment-orchestrator.
  3. Core service: Orchestrator Service.

Technical/design follow-up:

  1. Development team должна описать exact services/modules boundaries.
  2. Development team должна описать Pub/Sub topics/subscriptions.
  3. Development team должна описать database ownership and schema.
  4. DevOps/development team должна описать scaling/deployment strategy.
  5. Development team должна использовать application architecture decisions document as input.