refactored notificatoin / tgsettle responsibility boundaries

api/payments/orchestrator/main.go

@@ -15,3 +15,47 @@ func factory(logger mlogger.Logger, file string, debug bool) (server.Application
 func main() {
 	smain.RunServer("main", appversion.Create(), factory)
 }
+
+/*
+
+execute_payment_request_validator
+Validate meta.organization_ref, meta.trace.idempotency_key, quotation_ref, client_payment_ref shape (idempotency key is in trace: trace.proto (line 10)).
+
+payment_idempotency_service
+Fingerprint business payload (org + quotation_ref + client_payment_ref), dedupe create/retry behavior, and mismatch detection (same pattern as quote idempotency).
+
+quote_snapshot_resolver
+Resolve quotation_ref, enforce executable/non-expired quote, extract canonical intent_snapshot + quote_snapshot.
+
+payment_aggregate_factory_v2
+Create initial aggregate: state=CREATED, version=1, immutable snapshots, and initial step telemetry shell.
+
+execution_plan_compiler_v2
+Compile runtime step graph from quote route + execution conditions + intent.
+Important: do not reuse old route/template lookup path as primary (plan_builder route/template selection) because v2 quote already selected route.
+
+orchestration_state_machine
+Single source of truth for aggregate transitions (CREATED/EXECUTING/NEEDS_ATTENTION/SETTLED/FAILED) and step transitions (PENDING/RUNNING/COMPLETED/...).
+
+step_scheduler_runtime
+Pick runnable steps, manage dependency checks, retries/attempts, and mark blocked/skipped.
+
+step_executor_registry
+Rail/action executors (ledger, crypto, provider_settlement, card_payout, observe_confirm) behind interfaces.
+
+external_event_reconciler
+Consume async gateway/ledger/card events, map to step updates, append external refs, advance aggregate state.
+
+payment_repository_v2
+Persistence with optimistic concurrency (version CAS), plus indexes for:
+(org,payment_ref), (org,idempotency_key), (org,quotation_ref,created_at), (org,state,created_at).
+
+payment_query_service_v2
+GetPayment and ListPayments with v2 filters (states, quotation_ref, created_from/to, cursor) and efficient projections.
+
+payment_response_mapper_v2
+Map internal aggregate to proto Payment and enforce response invariants (same role as quote mapper/invariants).
+
+orchestration_observability
+Metrics, structured logs, audit timeline per payment and per step attempt.
+*/