Federated from workspace · PL-003 · zaixos-ai-platform/docs/PLATFORM_ARCHITECTURE.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

PL-003 Platform Architecture

Platform: ZAIXOS AI Platform (PL-003)
Repository: zaixos-ai-platform
Packages: zaixos/ai-contracts @ 0.2.0 · zaixos/ai-platform @ 0.7.0
Status: Operational — Consumer #1 pinned

Purpose

PL-003 is the shared AI intelligence infrastructure platform for the ZAIXOS workspace. It extracts reusable runtime machinery from product AI modules while preserving product ownership of business truth.

Boundary summary

Authoritative detail: ARCHITECTURE_BOUNDARY.md.

Owns (PL-003)	Does not own
Provider abstraction	Business truth
Prompt engine (schema + renderer)	Patients, orders, CRM
Conversation runtime API	ERP / domain logic
Job orchestration	Product workflows
Agent runtime framework (base)	Tenant authoritative records
Tool execution framework	Domain AI worker platforms
Memory, knowledge, context runtimes	Engineering methodology (ZEP)
AI configuration schema	AI UI shells (PL-002)
Policies (PII, HITL defaults)	Knowledge graph ontology
Evaluation schema + hooks	Production secrets
Observability (AI jobs)	ZIP orchestration (PL-004)

Package architecture

packages/contracts/     → zaixos/ai-contracts   (Layer 1)
packages/laravel/       → zaixos/ai-platform    (Layer 2)
prompts/ agents/ evals/                         (Layer 3)

See LAYER_MODEL.md.

Dependency direction

CO-001 → RP-002 → PL-001 (cite-only) → PL-003 (this) → PR-001 → future products
                                              ↑
PL-002 (Design System) — orthogonal; no dependency on PL-003
PL-004 (ZIP) — future; consumes PL-003 contracts; not implemented in this repo

No reverse dependencies. Products consume via Composer pin only.

Runtime modules (0.7.0)

Module	Responsibility
Providers	Gateway, factory, health, streaming, embeddings, fallback
Jobs	Orchestration, processing, lifecycle, cost estimation
Prompts	Engine, renderer, versioning, validation, inheritance
Conversations	Engine, lifecycle, history, context builder
Agents	Registry, permissions, capabilities, invocation pipeline
Tools	Registry, execution orchestrator
Memory	Working, conversation, long-term managers
Knowledge	Retrieval pipeline, ranking, filtering, compression
Context	Assembly, budget, prioritization, window management

Consumer model

Consumer #1 (PRD-001) pins zaixos/ai-platform ^0.7.0 and delegates through compatibility adapters. See CONSUMER_INTEGRATION.md.

Extraction method

Adapter delegation from PRD-001 app/Modules/AI/ — frozen product paths unchanged. See EXTRACTION_BOUNDARY.md and AI_PLATFORM_EXTRACTION_DISCOVERY.md.

Validation

Suite	Location	Count
Architecture	tests/Architecture/	55 tests
Runtime unit	packages/laravel/tests/	46 tests

composer test

Related documentation

Document	Role
ARCHITECTURE_BOUNDARY.md	Owns / does-not-own
RATIFICATION.md	Status and evidence
VERSIONING.md	Semver policy
WAVES.md	M-18 wave index