Ecommerce contract registry¶
| Attribute | Value |
|---|---|
| Registry version | 1.0-draft |
| Pilot boundary | Shopify, EUR, one Odoo company, order_invoice_v1 |
| Platform dependency | Accountify platform specification v0.3 |
| Architecture entrypoint | Ecommerce accounting architecture |
This registry defines the complete normative document set required to implement the ecommerce pilot. A contract marked documented is sufficiently specified for engineering design and estimation; it does not mean the feature is implemented, accounting-approved, security-approved, or production-enabled.
Required contract set¶
| ID | Contract | Authority | Accountable owner | Status |
|---|---|---|---|---|
EC-00 |
Architecture and scope | Runtime boundaries, identifiers, ownership, end-to-end flow | Platform architecture | Documented |
EC-01 |
Source capability and enablement | Connector/stream evidence, webhook coverage, drift, enablement gate | Integration engineering | Documented |
EC-02 |
Source ingestion | Receipt, tenant attribution, Airbyte runs, deduplication, freshness, replay | Data platform | Documented |
EC-03 |
Canonical commerce model | Entities, event envelope, monetary types, identity, state machines | Data architecture | Documented |
EC-04 |
Mappings and master data | Mapping lifecycle, precedence, effective dates, evidence, drift | Accounting integrations | Documented |
EC-05 |
Accounting policy | Posting grain, tax, dates, currency, rounding, journals, approval | Accounting owner | Documented; sign-off pending |
EC-06 |
API and event contract | HTTP resources, commands, event envelope, errors, compatibility | API architecture | Documented |
EC-07 |
Odoo posting | Model surface, commands, Online guarantees, markers, readback | Odoo engineering | Documented; clone proof pending |
EC-08 |
Settlements and payouts | Allocation, payout/bank matching, clearing, close, exceptions | Accounting operations | Documented; sign-off pending |
EC-09 |
Refunds, returns, disputes, and inventory | Financial/physical separation and inventory authority | Accounting and operations | Documented; sign-off pending |
EC-10 |
Warehouse marts and reporting | Dimensions, fact grains, metrics, refresh, lineage, reporting API | Data platform | Documented |
EC-11 |
Data governance | Classification, minimization, access, retention, deletion, offboarding | Security and privacy | Documented; approval pending |
EC-12 |
Operations and acceptance | Jobs, retries, SLOs, observability, test layers, rollout gates | Platform operations | Documented |
EC-13 |
Operational runbooks | Incident actions, evidence, exit criteria, escalation | Platform operations | Documented |
Contract precedence¶
When two documents appear to conflict, apply this order:
- Legal and regulatory obligations approved for the tenant and jurisdiction.
- Accountify platform specification for tenant isolation, identity, authorization, common operations, and Odoo execution profiles.
- This registry and architecture contract for ecommerce scope and ownership.
- The domain contract identified in the table above.
- Source-specific adapter notes, examples, and generated runtime model pages.
Examples and generated metadata cannot weaken a normative invariant. A discovered conflict blocks implementation until the accountable owners record the resolution and update every affected contract.
Cross-contract invariants¶
All contracts must preserve these invariants:
- Every durable row, object reference, job, event, mapping, mart row, export, and audit record is tenant-scoped.
- Source content never chooses its tenant, Odoo connection, company, model, method, journal, account, tax, warehouse, or policy.
- Money is a decimal value with explicit currency; accounting decisions never use binary floating-point.
- Delivery is at least once. Idempotency and deduplication are enforced at each boundary.
- An Odoo mutation is not successful until authoritative readback proves the expected business result.
- Odoo Online does not receive the HQ custom-module receipt guarantee.
- Orders, payments, fulfillments, refunds, returns, disputes, settlements, payouts, Odoo posting, and reconciliation advance independently.
- Marts are rebuildable reporting products and never become transactional workflow authority.
- Raw payload access and retention are controlled by data classification and approved policy.
- Unsupported accounting cases fail closed and create reviewable exceptions.
Required implementation artifacts¶
The repository now includes an executable post-Odoo pilot reference for readback persistence, transactional outbox delivery, warehouse facts, incremental marts, controls, reporting contracts, and monitoring. The following table remains the complete artifact obligation for the ecommerce pilot:
| Artifact | Contract source | Validation |
|---|---|---|
| OpenAPI document | EC-06 |
Reporting contract present; remaining command resources and runtime tests pending |
| Event JSON Schemas | EC-03, EC-06 |
Post-Odoo schemas present; remaining catalog schemas and compatibility tests pending |
| PostgreSQL migrations | EC-02 through EC-11 |
Post-Odoo readback/outbox/warehouse slice present; full domain schema and runtime migration evidence pending |
| Policy schemas | EC-04, EC-05, EC-09 |
Versioned fixtures and accounting approval |
| dbt/SQL mart models | EC-10 |
Initial post-Odoo marts and controls present; full commerce marts and runtime evidence pending |
| Source capability fixtures | EC-01 |
Connector catalog and pilot-store evidence |
| Odoo capability fixtures | EC-07 |
Representative clone workflow evidence |
| Incident procedures | EC-13 |
Tabletop and failure-injection exercises |
Hand-written documentation is not a substitute for these executable artifacts. Executable artifacts may be stricter, but may not weaken a documented invariant.
Change and approval matrix¶
| Change | Required approval |
|---|---|
| Source stream, cursor, connector version, webhook topic | Integration engineering and data platform |
| Canonical identity, amount, state, or event semantics | Data architecture and affected consumers |
| Mapping precedence or fallback | Accounting integrations and accounting owner |
| Tax, posting grain, date, journal, account, FX, rounding | Accounting owner |
| Odoo command, model, method, wrapper, or readback invariant | Odoo engineering, security, accounting owner |
| Mart grain or metric definition | Data platform and metric owner |
| Classification, access, retention, deletion, export | Security and privacy owner |
| Isolation, idempotency, authorization, or recovery guarantee | Platform architecture and security |
Every approved change records contract ID, old/new version, effective date, migration plan, compatibility window, test evidence, and rollback-of-release procedure.
Readiness status¶
The documentation contract set and post-Odoo pilot reference are complete for engineering implementation. Production remains gated by the missing artifact slices identified above, PostgreSQL/dbt integration evidence, pilot-store and Odoo-clone evidence, accounting/security approvals, shadow-run results, and the acceptance criteria in EC-12.