ADR: Product workflow v1

Status

Accepted

Date

2026-06-25

Context

MyHoreca Pay is a financial operations product for Indonesian bank payment files and bank statements. The product recognizes bank-specific formats, normalizes transactions, helps the user match counterparties and Syrve/iiko documents, and safely posts payments through the Syrve/iiko integration boundary.

The product is not a copy of a 1C workflow, a Russian INN-centric accounting process, or the standard iiko payment screen. iiko/1C material may be used only as background reading for domain terminology and integration constraints. It is not the source of truth for the MyHoreca Pay product workflow.

Indonesian banks use different export formats. A single hardcoded parser or one-bank product model is not acceptable. Each supported bank/format must be handled through a bank adapter or format detector boundary that converts external file structure into the internal normalized transaction model.

Posting to Syrve/iiko is financially sensitive. A successful posting request is not the same as successful reconciliation. Optimistic evidence is not financial truth; live readback and reconciliation checks are required.

This ADR is documentation-only. It must not introduce runtime backend or frontend code changes, real bank documents, real credentials, private customer data, or secrets.

Decision

MyHoreca Pay product workflow v1 is:

bank file
  -> bank adapter / format detector
  -> normalized transactions
  -> debit / credit interpretation
  -> counterparty wizard / matching rules
  -> Accountant review
  -> allocation to Syrve/iiko documents
  -> safe posting through IikoConnector
  -> reconciliation
  -> anomalies / notifications / audit

The normalized transaction model is the internal contract between bank adapters and the product workflow. Adapters may understand bank-specific layouts, columns, encodings, signs, CR/DB markers, account sections, dates, references, and descriptions. Downstream matching, allocation, review, posting, and reconciliation must consume normalized transactions instead of raw bank-file structures.

Debit/credit interpretation is an explicit product responsibility. It must not be hidden inside UI assumptions or copied from a single bank format. The system must preserve enough evidence to explain how a transaction was interpreted.

Counterparty matching is part of the product workflow. It includes wizard-assisted manual decisions and reusable matching rules. Matching decisions should be auditable and must support later improvement without changing the target product workflow.

The MVP workflow is Accountant-led. In MVP, Accountant can perform the full operational cycle: import/review normalized transactions, match counterparties, review allocation, approve safe posting when gates allow it, reconcile, and handle anomalies. PaymentOperator is a target/future role for separation of duties, but it is not a mandatory MVP dependency and must not block the MVP workflow.

Allocation must happen before posting. The product must map bank transactions to Syrve/iiko documents and allocation lines before any payment write is queued or executed.

Safe posting must go only through the IikoConnector boundary. MyHoreca Pay must not bypass the connector with ad hoc Syrve/iiko writes from UI, docs tasks, or unrelated services.

Reconciliation happens after posting. Posting success means the write call was accepted or completed according to posting evidence; reconciliation success requires live readback and expected financial state checks.

Anomalies, notifications, and audit are mandatory safety layers, not optional reporting features.

Product workflow

1. Bank file import receives a bank statement or payment file without adding real customer files to the repository.
2. Bank adapter / format detector identifies the bank and format, then delegates parsing to the matching adapter.
3. Normalized transactions are produced as the stable internal contract for downstream processing.
4. Debit / credit interpretation determines financial direction using bank-format evidence and product rules.
5. Counterparty wizard / matching rules connect normalized transactions to known counterparties and preserve manual or rule-based decisions.
6. Accountant review validates imported transactions, matching confidence, and proposed actions in the MVP workflow.
7. Allocation to Syrve/iiko documents maps transaction amounts to open Syrve/iiko documents before posting.
8. Safe posting through IikoConnector queues and executes writes only through approved integration boundaries and safety gates.
9. Reconciliation performs live readback and compares actual state with expected financial state after posting.
10. Anomalies / notifications / audit record mismatches, alert users, block unsafe retries, and preserve traceability.

Roles and responsibilities

Role	Product responsibility
Accountant	MVP owner of the full workflow: import review, matching, allocation, approval when gates allow it, reconciliation, anomaly handling, and audit review.
PaymentOperator	Target/future operational role for upload, matching, and allocation preparation. It is not required as a separate MVP role.
Viewer	Read-only access to imports, documents, allocations, postings, reconciliation, anomalies, notifications, and audit.
LocationAdmin	Target role for location-scoped settings and Syrve/iiko connection administration; no default payment write authority.
OrganizationAdmin	Target role for organization setup, users, locations, and connection administration; no direct production posting authority.
MegaManager	Target support/onboarding role for pilot customers; no payment approval or production write enablement.
MegaAdmin	Platform control over quotas and production enablement gates; not a routine payment operator.

Safety gates

Production write must not be enabled by one global permanent flag. Production write requires layered gates:

• Tenant and location enablement before any production write is considered.
• Explicit approval by an authorized role for the specific posting or controlled run.
• Idempotency key and request hash checks to prevent duplicate or mutated writes.
• Method-specific preflight checks before write execution.
• Allocation completed before posting.
• Reconciliation and anomaly checks before retrying or continuing a risky flow.
• Open Critical anomaly blocks repeat write for the same external document.
• Live readback is preferred over optimistic evidence for financial truth.
• Posting success is tracked separately from reconciliation success.
• Audit entries for import, interpretation, matching, allocation, approval, posting, reconciliation, anomaly, notification, and manual override actions.

Non-goals

• Не строим копию 1С.
• Не строим копию стандартного iiko payment screen.
• Не проектируем российский ИНН/1С-centric workflow.
• Не одобряем production write без scoped authorization, manual approval и safety checks.
• Не добавляем реальные банковские документы в репозиторий.
• Не меняем runtime-код в этой задаче.
• Не вводим новые бизнес-решения без отдельного ADR.

How AI agents must use this ADR

• Read this ADR before tasks related to bank import, bank adapters, normalized transactions, debit/credit interpretation, matching, allocation, posting, reconciliation, roles, safety gates, anomalies, notifications, or audit.
• If a new task conflicts with this ADR, do not implement the conflict silently. Propose a new ADR or an update to this ADR first.
• Do not use the iiko/1C article or standard iiko payment screen as the source of truth for MyHoreca Pay.
• Do not narrow the product to one bank format or one hardcoded parser. Preserve the adapter boundary.
• Always-on runtime capability is not authorization. Preserve tenant/location scope, mandatory manual approval, idempotency, preflight, reconciliation/anomaly checks, and audit.
• Update documentation together with any workflow or safety decision changes.
• Do not add real bank files, real requisites, credentials, secrets, or private customer data to docs or fixtures.
• Do not make runtime backend/frontend code changes as part of an ADR-only task.

Consequences

• Future product, backend, frontend, and integration tasks must align with the workflow in this ADR unless another accepted ADR changes it.
• Bank adapter work must produce normalized transactions and preserve interpretation evidence.
• Matching, allocation, posting, reconciliation, anomalies, notifications, and audit are one product workflow, not unrelated screens.
• MVP implementation decisions must keep Accountant capable of completing the workflow without requiring PaymentOperator as a separate role.
• Production write remains blocked until the safety gates are implemented and documented for the relevant tenant/location.

Related documents

• Product scope
• User roles
• Current architecture state
• MyHoreca Pay roadmap
• Implementation backlog