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

---

PL-003 Consumer Integration

Status: Operational — Consumer #1 (PR-001 / PRD-001) pinned @ zaixos/ai-platform ^0.7.0

Registered consumer

Consumer	ID	Pin	Status
Dental Clinic Revenue Operating System	PR-001 / RP-004	zaixos/ai-platform ^0.7.0	Operational

Registry edge: CM-010 (PR-001 → PL-003) — see zaixos-registry/REGISTRY_CONSUMER_MAP.md.

---

Composer integration

Path repositories (local monorepo)

Add to consumer composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../zaixos-ai-platform/packages/contracts",
            "options": { "symlink": true }
        },
        {
            "type": "path",
            "url": "../zaixos-ai-platform/packages/laravel",
            "options": { "symlink": true }
        }
    ]
}

Require packages

composer require zaixos/ai-platform:^0.7.0

Transitive dependency: zaixos/ai-contracts ^0.2.0.

Service provider

Zaixos\Ai\Laravel\Providers\AiPlatformServiceProvider registers automatically via Composer extra.laravel.providers.

Platform config merges from packages/laravel/config/ai.php. Consumer config/ai.php may override provider driver classes.

---

Compatibility layer (PRD-001 reference)

PRD-001 implements thin adapters under app/Modules/AI/Application/Compatibility/ and .../Adapters/:

Component	Role
ClinicTenantMapper	clinicId ↔ tenantId passthrough
AiPlatformDtoMapper	Product DTOs ↔ Zaixos\Ai\Contracts DTOs
AiProviderGatewayAdapter	Capability gates → PL-003 ProviderGateway
AiJobRuntimeAdapter	Job orchestrator + Eloquent persistence
AiPromptEngineAdapter	PromptEngine / PromptRenderer
AiConversationRuntimeAdapter	Eloquent sync + ConversationEngine
AiMemoryRuntimeAdapter	Eloquent + MemoryRuntime
AiKnowledgeRuntimeAdapter	KnowledgeRuntime + product vector store
AiAgentRuntimeAdapter	AgentRuntime + assistant registry
ProductVectorStoreBridge	Platform VectorStoreContract → product store

Legacy product services remain thin delegation facades only.

Full Wave 8 detail: WAVE_8_CONSUMER_INTEGRATION.md.

---

Architecture gates (consumer)

PRD-001 validates integration with:

• tests/Architecture/AiPlatformInfrastructureTest.php
• tests/Architecture/AiPlatformDelegationTest.php

PL-003 validates with workspace architecture tests under tests/Architecture/ and runtime unit tests under packages/laravel/tests/.

---

Integration steps (new consumers)

1. Add path or Packagist repositories for packages/contracts and packages/laravel.
2. composer require zaixos/ai-platform:^0.7.0 (or current semver per VERSIONING.md).
3. Ensure AiPlatformServiceProvider is discovered (or register manually).
4. Bind product persistence adapters to PL-003 store contracts — do not fork runtime logic.
5. Add consumer architecture tests proving delegation, not duplication.
6. Register consumer edge in zaixos-registry when pin is evidenced.

---

Forbidden

• Copying PL-003 source into product repos
• Ungoverned prompt paths outside catalog registration
• Direct provider SDK imports outside PL-003 provider module
• Migrating product business logic into PL-003

---

Performance note

Consumer integration adds a thin adapter hop (DTO mapping + capability assert). Expected overhead ≤5% vs pre-integration product gateway for stub completion. Retries remain in PL-003 ProviderFallbackStrategy.