MahalliMahalli Handbook
Architecture Decision Records

ADR-0006: Simplified invoicing in the core, full accounting as an add-on

The core generates and stores a ZATCA simplified invoice for every payment; full accounting is a Marketplace add-on delivered by an embedded partner first.

ADR-0006: Simplified invoicing in the core, full accounting as an add-on

  • Date: 2026-09-18
  • Status: Proposed (seed — awaiting the owner's approval)
  • Deciders: the owner, Claude (seed)
  • Tags: domain compliance revenue

Context

Every payment in Saudi Arabia must issue a ZATCA-compliant invoice. Full accounting (general ledger, expenses, tax returns) is a separate market with strong competitors.

Decision

The core generates and stores a simplified invoice (QR TLV, XML) for every payment. Full accounting is a Marketplace add-on: an embedded partner first, with an in-house build evaluated after Phase 4 if demand exceeds 30% of merchants.

  • ZATCA path (in-house / partner): Q4.

Consequences

  • Positive — compliance from day one without building accounting; the team stays focused on the wedge.
  • Negative — dependence on an accounting partner for margins and user experience.
  • Revenue impact (SAR / month, confidence) — the accounting share of R4 ≈ 10,000–15,000 at 1,000 merchants (low confidence).

Rejected alternatives

  • Building full accounting in Phase 1: delays the wedge and enters a crowded market.
  • No invoicing in the core: violates ZATCA and blocks payments.

References

  • docs/00-vision.md, docs/02-architecture.md

On this page