ZAIXOS Engineering Platform — Technical Architecture

Document type: Master Technical Architecture
Version: 1.0 · Phase: 12-3
Status: Permanent technical authority
Governance: PLATFORM_CONSTITUTION.md · PLATFORM_BOUNDARIES.md
Product: product/PRODUCT_INDEX.md

Purpose

Define how ZEP works internally — layers, packages, flows, states, and rules — so an engineering team can implement the platform without making architectural decisions.

This document is implementation-independent: no repository creation, no PHP code, no Composer package build. It is the permanent technical blueprint.

Design goals (normative)

Goal	Technical expression
Product independent	Platform packages contain zero product domain
Adapter independent	Core + contracts have no IDE-native paths
Runtime independent	Runtime Components are abstract obligations
Vendor independent	Adapter layer isolates Cursor and future IDEs
Implementation independent	Specs precede code in every layer
Ten-year maintainability	Semver, contracts@N, lock files, validation gates
Single source of truth	One canonical doc per topic (Rule B5)

Platform layer model

┌─────────────────────────────────────────────────────────────────────────────┐
│ L7  Consumer Integration     product repo: .zaixos/ · platform.lock · CI   │
├─────────────────────────────────────────────────────────────────────────────┤
│ L6  Validation               contract · manifest · workspace · extension    │
├─────────────────────────────────────────────────────────────────────────────┤
│ L5  Materialization          merge core + adapter + extensions → mounts     │
├─────────────────────────────────────────────────────────────────────────────┤
│ L4  Adapter                  certified workspace templates · metadata       │
├─────────────────────────────────────────────────────────────────────────────┤
│ L3  Runtime Abstraction      components · manifests · schemas · spec      │
├─────────────────────────────────────────────────────────────────────────────┤
│ L2  Contracts                contracts@1 · JSON schemas · obligations       │
├─────────────────────────────────────────────────────────────────────────────┤
│ L1  Methodology & Templates  workflow · reports · RESPONSE_TEMPLATE         │
├─────────────────────────────────────────────────────────────────────────────┤
│ L0  Governance (read-only)   constitution · boundaries · ADRs · versioning  │
└─────────────────────────────────────────────────────────────────────────────┘
         ▲                              ▲
         │                              │
    Product (D-R)                  IDE session (D-T)
    consumes L1–L6                 reads adapter mount only

Dependency direction: L0 → L1 → … → L6. L7 depends on L1–L6. No upward dependency.

Architecture rules (normative)

ID	Rule
AR-01	Platform never depends on Products
AR-02	Products always depend on Platform (Public surfaces only)
AR-03	Contracts never depend on Adapters
AR-04	Adapters implement Contracts
AR-05	Validation depends on Contracts (and Public schemas)
AR-06	Installer depends on Contracts and Public config schemas
AR-07	Knowledge never depends on Runtime (native IDE)
AR-08	Templates never depend on Products
AR-09	Products extend; Products never modify Platform Core
AR-10	No circular dependencies
AR-11	Documentation First
AR-12	Contracts First
AR-13	Validation First
AR-14	Architecture Before Implementation
AR-15	Single Source of Truth
AR-16	Stable Public APIs
AR-17	Explicit Ownership (D-P, D-R, D-A, D-V, D-T)
AR-18	Extension Before Modification
AR-19	Long-term Compatibility

Package graph (logical)

See PACKAGE_ARCHITECTURE.md.

pkg-governance (read-only refs)
    └── pkg-methodology
            └── pkg-contracts
                    ├── pkg-runtime-spec
                    ├── pkg-validation
                    └── pkg-adapters
                            └── pkg-templates
                                    └── pkg-knowledge

Distribution unit: Single Composer package zaixos/engineering-platform containing all logical packages as internal paths (TDR-001).

Dependency graph

See DEPENDENCY_MODEL.md.

Product ──depends──► Platform Public API
Platform Core ──depends──► Contracts
Adapter ──implements──► Contracts
Validation ──depends──► Contracts + Adapter metadata
Materialization ──depends──► Core + Adapter + Extensions
Extensions ──depends──► Extension schema (Public)
Knowledge ──depends──► Nothing runtime-native

Execution graph

See EXECUTION_ARCHITECTURE.md · EXECUTION_PIPELINE.md.

Developer → Platform pin → Workflow → Procedure → Delegate
    → Constraints → Hooks → Validation → Runtime Report
    → Architecture Review → Acceptance → Freeze → Release

Installation flow

See INSTALLATION_ARCHITECTURE.md.

Resolve version (platform.yml constraint + lock)
    → Fetch platform (Composer primary)
    → Verify checksum
    → Lay down .zaixos/platform/
    → Register extensions manifest
    → Materialize adapter
    → Run bootstrap validation
    → Record lock

Bootstrap flow (product developer first session)

Clone product repo
    → Read platform.lock
    → Verify vendor/platform present
    → Verify .zaixos/ tree complete
    → Verify adapter mount (.cursor/ for cursor-adapter-v1)
    → Run validation suite (local)
    → Open IDE (native session)

Materialization flow

See RUNTIME_MATERIALIZATION.md.

Load platform core snapshot (immutable at pin)
    → Load certified adapter template
    → Merge extension registry (manifest.yml)
    → Apply precedence rules
    → Write .zaixos/adapters/{id}/
    → Create IDE mount (symlink or copy)
    → Compute checksum → update lock

Validation flow

See VALIDATION_ARCHITECTURE.md.

Config validation (yaml schemas)
    → Contract reference validation
    → Manifest parity (counts, IDs)
    → Adapter workspace existence
    → Extension schema + limits
    → Architecture tests (product-owned, separate suite)
    → Emit validation report

Configuration hierarchy

See CONFIGURATION_ARCHITECTURE.md.

Platform release defaults (in package)
    └── .zaixos/platform.yml (product declarative)
            └── .zaixos/platform.lock (product exact pin)
                    └── .zaixos/extensions/manifest.yml (product extensions)
                            └── IDE session (ephemeral — not platform config)

Precedence: lock overrides yaml drift warnings; extensions cannot override platform constraints A–B.

State machine (platform assets)

See PLATFORM_STATE_MACHINE.md.

Draft → Specified → Reviewed → Approved → Implemented → Validated → Released → Deprecated → Archived

Phase work products use the same state machine; Released platform assets receive semver tags.

Lifecycle matrix

See ASSET_LIFECYCLE.md for per-asset: Platform, Contract, Workflow, Procedure, Rule, Template, Knowledge, Adapter, Manifest, ADR, RFC, Validation Suite, Configuration, Documentation.

Evolution matrix

See EVOLUTION_MODEL.md.

Change type	Authority	Version bump	Migration
Additive Public	Platform MINOR	MINOR	Optional lock refresh
Breaking Public	ADR + MAJOR	MAJOR	Required guide
Contract obligation	New contracts@N	Platform MAJOR	Adapter re-cert
Extension only	Product	None on platform	Product manifest
Adapter fix	Adapter PATCH	PATCH	Rematerialize

Compatibility matrix (platform 1.x baseline)

Platform	contracts@	Adapters	Extension schema	Lock schema
1.0.x	1	cursor-adapter-v1	v1	v1
1.x.x	1	cursor-adapter-v1	v1	v1

Contract obligation changes require contracts@2 and platform 2.0.0 — out of 1.x scope.

Extension graph

See EXTENSION_ARCHITECTURE.md.

Platform Core (immutable)
    ├── Default manifests
    ├── Adapter template
    └── Extension manifest (product)
            ├── procedures/
            ├── workflows/
            ├── agents/
            ├── rules/
            └── knowledge/
                    ↓ merge at materialization
            Effective runtime view (read-only merge result)

Consumer integration flow

Product declares platform.yml
    → Pins platform.lock
    → Registers extensions
    → CI invokes validation entrypoint
    → Developer uses materialized adapter
    → Phase execution pipeline (EXECUTION_PIPELINE)
    → Architect acceptance (RESPONSE_TEMPLATE)
    → Product release (independent semver)
    → Platform upgrade (lock bump + migration guide)

Version resolution flow

See INSTALLATION_ARCHITECTURE.md · EVOLUTION_MODEL.md.

platform.yml versionConstraint (semver range)
    + platform.lock exact version (authoritative for production)
    + composer.lock package hash
    → Resolve to single platform@X.Y.Z + adapter@A.B.C + contractMajor=N
    → Reject if lock drift without explicit bump

Rollback flow

Record failing validation or release incident
    → Restore previous platform.lock from VCS
    → composer install (exact previous versions)
    → Rematerialize adapter
    → Re-run validation
    → Architect documents rollback in phase report

Embedded ERP rollback (transitional): restore tag v5.1-engineering-runtime-platform per PLATFORM_VERSIONING_POLICY.md.

Upgrade flow

Review platform CHANGELOG + compatibility matrix
    → Bump platform.yml constraint (if needed)
    → Update platform.lock (exact)
    → composer update zaixos/engineering-platform
    → Apply migration guide (MAJOR only)
    → Rematerialize
    → Full validation + Architect review for MAJOR

Failure recovery flow

Failure class	Stop condition	Recovery
Validation fail	CI red	Fix artifact or extension; never weaken tests
Materialization fail	Incomplete mount	Re-run materialization; verify checksum
Lock drift	Warning or fail	Align lock with intended pin
Adapter gap	Capability register	Architect accepts gap or waits for adapter MINOR
Contract mismatch	Hard fail	Pin compatible adapter; no contract edits in product

Canonical namespace (product repo)

Path	Owner	Purpose
`.zaixos/platform.yml`	D-R	Declarative integration
`.zaixos/platform.lock`	D-R	Exact pin + checksum
`.zaixos/platform/`	D-P content, D-R instance	Vendored or linked platform tree
`.zaixos/extensions/`	D-R	Registered extensions
`.zaixos/adapters/{id}/`	D-A template, D-R mount	Canonical adapter storage
`.cursor/`	D-A via mount	Cursor IDE read path (cursor-adapter-v1)

Relationship to Runtime Contracts

Runtime Contracts define what adapters must implement. Technical architecture defines how platform packages, configs, and flows connect to deliver and verify those implementations.

No conflict: Technical architecture does not add, remove, or redefine contract obligations.

Document map

Concern	Document
Packages	PACKAGE_ARCHITECTURE.md
Dependencies	DEPENDENCY_MODEL.md
Installation	INSTALLATION_ARCHITECTURE.md
Configuration	CONFIGURATION_ARCHITECTURE.md
Extensions	EXTENSION_ARCHITECTURE.md
Materialization	RUNTIME_MATERIALIZATION.md
Validation	VALIDATION_ARCHITECTURE.md
Public API (technical)	PUBLIC_API_ARCHITECTURE.md
Config reference	PLATFORM_CONFIGURATION_REFERENCE.md
Decisions	TECHNICAL_DECISION_RECORDS.md
Execution	EXECUTION_ARCHITECTURE.md · EXECUTION_PIPELINE.md
States	PLATFORM_STATE_MACHINE.md
Lifecycles	ASSET_LIFECYCLE.md
Evolution	EVOLUTION_MODEL.md

Technical Architecture v1.0 — Phase 12-3. Permanent authority before Repository Extraction Planning (12-4).

ZAIXOS Engineering Platform — Technical Architecture ​

Purpose ​

Design goals (normative) ​

Platform layer model ​

Architecture rules (normative) ​

Package graph (logical) ​

Dependency graph ​

Execution graph ​

Installation flow ​

Bootstrap flow (product developer first session) ​

Materialization flow ​

Validation flow ​

Configuration hierarchy ​

State machine (platform assets) ​

Lifecycle matrix ​

Evolution matrix ​

Compatibility matrix (platform 1.x baseline) ​

Extension graph ​

Consumer integration flow ​

Version resolution flow ​

Rollback flow ​

Upgrade flow ​

Failure recovery flow ​

Canonical namespace (product repo) ​

Relationship to Runtime Contracts ​

Document map ​