ADR-005 — Platform vs Product Separation
Status: Accepted
Date: 2026-06-28
Phase: 12-1A
Deciders: Platform Architect
Authority: PLATFORM_BOUNDARIES.md
Context
Dental Clinic ROS mixes Laravel application runtime, product architecture (ANPA, MODULE_BOUNDARIES), and ERP engineering platform. Phase 11-11 operational acceptance identified onboarding confusion and extraction blockers from dual stacks.
ZEP requires an immutable boundary between platform and product that survives extraction and multi-product reuse.
Decision
Separation model
| Concern | Platform (ZEP) | Product (e.g. Dental Clinic) |
|---|---|---|
| Purpose | How we engineer | What we build |
| Runtime | IDE engineering session | Laravel / application |
| Governance | Platform Constitution | Project Constitution |
| Boundaries | Extension registry | Module boundaries |
| Releases | zaixos-platform@v* | v*-product-name |
| Tests | Manifest parity, contracts | Modules, features, domain |
| AGENTS.md | Pointer to platform guide | Application + Filament context |
| Compliance | Engineering process only | Domain compliance (healthcare, etc.) |
Hard rules
- No product domain references in platform normative documents
- No platform contract edits in product repos
- Product extensions only through
.zaixos/extensions/manifest.yml - Single owner per asset — see PLATFORM_BOUNDARIES
- Independent freeze — product tag records platform pin
Distribution (resolved for v1.0 GA)
| Mechanism | Classification | Role |
|---|---|---|
Composer package zaixos/engineering-platform | Public | Primary integration for PHP/Laravel products |
| Git submodule to platform repo | Public | Transition + non-Composer consumers |
| Git template | Experimental | Greenfield — Phase 13+ |
| CLI installer | Experimental | Phase 13+ |
| Platform generator | Experimental | Phase 14+ |
Primary integration path for Dental Clinic: Composer package + platform.lock — no ambiguity for Phase 12-2 planning.
Transitional state (Dental Clinic)
Until Phase 12-7:
- Embedded
docs/development/ERP docs remain content authority hosted in product - Platform repo becomes canonical host at extraction
- Parity tests required before embedded removal
Consequences
Positive
- Restaurant, School, ERP SaaS reuse same platform
- Product architects focus on domain; platform architect on engineering
- Extraction scope is explicit
Negative
- Two constitution documents to understand
- Migration effort for Dental Clinic
Alternatives considered
| Alternative | Rejected because |
|---|---|
| Single constitution for all | Product domain pollutes platform |
| Platform inside Laravel module | Couples PHP-only; wrong layer |
| Copy ERP per product without package | Drift |
ADR-005 — Platform builds engineering; products build business systems.