ADR-001 — Why ZEP Exists
Status: Accepted
Date: 2026-06-28
Phase: 12-1A
Deciders: Platform Architect
Authority: PLATFORM_CONSTITUTION.md
Context
ZAIXOS ships multiple products (Dental Clinic ROS, future Restaurant, School, ERP SaaS, AI products). ERP v1.0 was embedded in the Dental Clinic repository as EOS + Runtime Contracts + Cursor Adapter v1. This coupling causes:
- Governance drift when copying ERP to new products
- Unclear ownership between product architecture and engineering runtime
- Extraction blockers (AGENTS.md, product releases, PHPUnit coupling)
- Phase numbering and documentation conflicts at operational acceptance (Phase 11-11)
A standalone ZAIXOS Engineering Platform (ZEP) is required before multi-product scale.
Decision
Create ZAIXOS Engineering Platform (ZEP) as a product-independent platform that packages:
- Engineering methodology (EOS → Platform Core)
- Runtime abstraction and contracts (ERP → Platform Runtime + Contracts)
- Certified adapters (Cursor v1 first)
- Validation, templates, and developer documentation
Products consume ZEP via pinned version — they do not embed authoritative copies long-term.
Embedded ERP in Dental Clinic is transitional legacy until Phase 12-7 migration; semantics frozen at ERP v1.0 / platform 1.0.0.
Consequences
Positive
- Single engineering foundation for all products
- Stable Runtime Contracts for multi-year adapter evolution
- Clear extraction path documented in Phases 12-1 through 12-2A; execution from 12-4 onward
- Product repos shrink to domain + architecture + platform pin
Negative
- Dual-maintenance period during migration
- Initial investment in platform repository and Composer package
- Teams must learn
.zaixos/namespace and lock file
Neutral
- ERP v1.0 tag
v5.1-engineering-runtime-platformremains valid historical baseline - Phase 10 EOS specs remain frozen historical reference
Alternatives considered
| Alternative | Rejected because |
|---|---|
| Keep ERP embedded per product | Guaranteed drift |
| Monorepo all products + ERP | Violates product independence |
| Composer-only without platform repo | Insufficient for non-PHP products |
| Fork ERP per product | No contract stability |
Compliance
- Does not change Runtime Contract obligations
- Does not modify adapter workspace semantics
- Extraction deferred to Phase 12-4 (planning) and 12-6 (execution) — after Phase 12-3 Technical Architecture
ADR-001 — foundational decision for ZEP.