Federated from workspace ·
PRD-001·Dental Clinic Revenue Operating System/docs/architecture/MODULE_BOUNDARIES.mdDo not edit canonical truth here — update the source repo, then re-runnpm run docs:sync.
Module Boundaries
Status: Permanent reference
Applies to: All platforms listed below
Enforcement: tests/Architecture/ModuleBoundaryTest.php + per-platform architecture tests
Each platform is a frozen integration boundary unless marked In progress. External code may depend only on the listed Public Contract and public DTOs.
Legend
| Column | Meaning |
|---|---|
| Responsibilities | What the platform owns |
| Public Contract | Sole importable application API |
| Module | Primary code location |
| Allowed Dependencies | Contracts/events that may be consumed |
| Forbidden Dependencies | Must never be imported directly |
| Ownership | Team/domain ownership |
| Freeze | Canonical git tag |
Finance
| Responsibilities | Clinic patient billing, invoices, payments, credit notes, refunds, adjustments, financial reporting, integrity assertions |
| Public Contract | App\Modules\CRM\Application\Contracts\FinancialQueryContract |
| Module | app/Modules/CRM/ (finance subdomain) |
| Allowed Dependencies | Shared contracts, Compliance events |
| Forbidden Dependencies | CRM Infrastructure\Models from other modules; direct finance service imports |
| Ownership | CRM / Finance domain |
| Freeze | finance-v1.0 — see docs/FINANCE-V1-FROZEN.md |
Billing
| Responsibilities | SaaS subscription billing, lifecycle, provider abstraction, outbox sync, webhooks, customer portal billing |
| Public Contract | App\Modules\Saas\Application\Contracts\BillingProviderContract (+ orchestrator entry points documented in v1.3 release) |
| Module | app/Modules/Saas/ |
| Allowed Dependencies | Shared, EntitlementContract, Finance isolation via architecture tests |
| Forbidden Dependencies | Finance internal services; direct Stripe SDK outside provider layer |
| Ownership | SaaS / Billing |
| Freeze | v1.3-billing-platform |
Product
| Responsibilities | Platform admin UI, organization/tenant/subscription management presentation, platform RBAC, operator dashboards |
| Public Contract | Platform Filament resources + AuthorizesPlatformAccess permission model (presentation layer; writes delegate to Saas actions) |
| Module | app/Filament/ (Platform group) + app/Modules/Saas/ |
| Allowed Dependencies | Saas orchestrators, EntitlementContract, BillingProviderContract |
| Forbidden Dependencies | Direct billing provider SDK; finance internals |
| Ownership | SaaS / Product |
| Freeze | v1.4-product-layer |
Customer Experience
| Responsibilities | Onboarding funnel, email verification, org/clinic wizards, invitations, trial journey UX |
| Public Contract | Middleware + Filament onboarding pages (writes via existing Saas/CRM actions) |
| Module | app/Filament/, app/Http/, config/saas.php (customer_experience) |
| Allowed Dependencies | Saas provisioning, Product layer permissions |
| Forbidden Dependencies | Billing orchestrator internals; finance |
| Ownership | SaaS / Customer Experience |
| Freeze | v1.5-customer-experience |
Entitlements
| Responsibilities | Feature gating, plan entitlements, quota enforcement |
| Public Contract | App\Modules\Saas\Application\Contracts\EntitlementContract |
| Module | app/Modules/Saas/ |
| Allowed Dependencies | Shared, Billing lifecycle state |
| Forbidden Dependencies | Finance internals; direct subscription model access from other modules |
| Ownership | SaaS / Entitlements |
| Freeze | v1.6-entitlements |
Public API
| Responsibilities | Versioned REST API (/api/v1), Sanctum auth, envelopes, pagination, rate limiting, OpenAPI |
| Public Contract | HTTP routes in routes/api.php + ApiRequestContext (no business logic in controllers) |
| Module | app/Http/, config/api.php |
| Allowed Dependencies | Module query/command contracts, EntitlementContract |
| Forbidden Dependencies | Infrastructure models in controllers; cross-module services |
| Ownership | Platform / API |
| Freeze | v1.7-public-api / v1.7.1-platform-hardening |
Integrations
| Responsibilities | Integration registry, provider abstraction, sync dispatch |
| Public Contract | IntegrationRegistryContract, IntegrationProviderContract, ConnectorContract |
| Module | app/Modules/Integrations/ |
| Allowed Dependencies | Shared, domain events |
| Forbidden Dependencies | CRM/Finance internals |
| Ownership | Platform / Integrations |
| Freeze | v1.8-integrations-platform |
Marketplace (Connector Marketplace)
| Responsibilities | Connector catalog, marketplace registry, connector hardening |
| Public Contract | ConnectorRegistryContract, ConnectorContract |
| Module | app/Modules/Integrations/ |
| Allowed Dependencies | Integrations platform contracts |
| Forbidden Dependencies | Provider implementations from consumer modules |
| Ownership | Platform / Integrations |
| Freeze | v1.9-connector-marketplace |
AI Platform
| Responsibilities | AI provider abstraction, agent/tool contracts, embedding and vector store boundaries |
| Public Contract | App\Modules\AI\Application\Contracts\AiPlatformContract |
| Module | app/Modules/AI/ |
| Allowed Dependencies | Shared |
| Forbidden Dependencies | CRM/Finance internals; direct provider SDK outside AI module |
| Ownership | AI Platform |
| Freeze | v2.0-ai-platform |
AI Runtime
| Responsibilities | Runtime execution layer, streaming, tool dispatch, provider connectivity |
| Public Contract | AiProviderContract, AiStreamingProviderContract, AiAgentContract, AiToolHandlerContract |
| Module | app/Modules/AI/ |
| Allowed Dependencies | AiPlatformContract |
| Forbidden Dependencies | Application-layer bypass of provider contracts |
| Ownership | AI Platform |
| Freeze | v2.1-ai-runtime |
AI Applications
| Responsibilities | Application-layer AI features, composed on runtime |
| Public Contract | Application services exposed via AiPlatformContract surface |
| Module | app/Modules/AI/ |
| Allowed Dependencies | AI Runtime contracts |
| Forbidden Dependencies | Direct infrastructure from other modules |
| Ownership | AI Platform |
| Freeze | v2.2-ai-applications |
Workspace
| Responsibilities | Workspace query surface, widgets, data providers, activity aggregation foundation |
| Public Contract | WorkspaceQueryContract, WorkspaceActivityPlatformQueryContract |
| Module | app/Modules/Workspace/ |
| Allowed Dependencies | Shared, CRM read contracts (via providers) |
| Forbidden Dependencies | CRM write services; finance |
| Ownership | Workspace |
| Freeze | v2.3-workspace |
Notification
| Responsibilities | Notification inbox, activity hub, timeline/inbox/reminder presentation |
| Public Contract | NotificationInboxContract, WorkspaceActivityPlatformQueryContract |
| Module | app/Modules/Workspace/ + app/Filament/Pages/Workspace/ |
| Allowed Dependencies | Workspace providers, Shared notification handlers |
| Forbidden Dependencies | Direct notification persistence from Filament |
| Ownership | Workspace / Notifications |
| Freeze | v2.4-notification-platform |
Search
| Responsibilities | Unified search providers, collaboration search surface |
| Public Contract | SearchProviderContract, MentionProviderContract |
| Module | app/Modules/Workspace/ |
| Allowed Dependencies | Workspace contracts, CRM read queries |
| Forbidden Dependencies | Direct Eloquent search across modules |
| Ownership | Workspace / Search |
| Freeze | v2.5-search-collaboration |
Realtime
| Responsibilities | Presence, broadcasting abstraction, realtime platform signals |
| Public Contract | App\Modules\Realtime\Application\Contracts\RealtimePlatformContract |
| Module | app/Modules/Realtime/ |
| Allowed Dependencies | Shared |
| Forbidden Dependencies | WebSocket infrastructure from consumer modules |
| Ownership | Realtime |
| Freeze | v2.6-realtime-platform |
Workflow
| Responsibilities | Workflow execution platform, triggers, actions, state |
| Public Contract | App\Modules\Workflow\Application\Contracts\WorkflowPlatformContract |
| Module | app/Modules/Workflow/ |
| Allowed Dependencies | Shared, port contracts (WorkflowNotificationPortContract, etc.) |
| Forbidden Dependencies | CRM internals from workflow engines |
| Ownership | Workflow |
| Freeze | v2.7-workflow-platform |
Workflow Designer
| Responsibilities | Visual workflow design, definition registry, designer UI |
| Public Contract | WorkflowPlatformContract (design-time operations subset) |
| Module | app/Modules/Workflow/ + Filament designer pages |
| Allowed Dependencies | Workflow platform |
| Forbidden Dependencies | Direct workflow execution from designer without platform contract |
| Ownership | Workflow |
| Freeze | v2.8-workflow-designer |
Analytics
| Responsibilities | Analytics platform, KPI queries, metric data providers |
| Public Contract | AnalyticsPlatformContract, AnalyticsReadQueryContract |
| Module | app/Modules/Analytics/ |
| Allowed Dependencies | Shared, MetricDataProviderContract implementations |
| Forbidden Dependencies | CRM infrastructure from analytics consumers |
| Ownership | Analytics |
| Freeze | v2.9-analytics-platform |
Advanced Analytics
| Responsibilities | Trend detection, benchmarking, advanced read queries |
| Public Contract | App\Modules\Analytics\Application\Advanced\Contracts\AnalyticsAdvancedReadQueryContract |
| Module | app/Modules/Analytics/Application/Advanced/ |
| Allowed Dependencies | Analytics platform |
| Forbidden Dependencies | Direct analytics service imports from other modules |
| Ownership | Analytics |
| Freeze | v3.0-advanced-analytics |
Operational Intelligence
| Responsibilities | Health scores, operational insights, enrichment ports |
| Public Contract | App\Modules\OperationalIntelligence\Application\Contracts\OperationalIntelligenceContract |
| Module | app/Modules/OperationalIntelligence/ |
| Allowed Dependencies | AnalyticsAdvancedReadQueryContract (read only) |
| Forbidden Dependencies | Analytics internal services |
| Ownership | Operational Intelligence |
| Freeze | v3.1-operational-intelligence |
Autonomous Operations
| Responsibilities | Autonomous decision enrichment, operations orchestration preview |
| Public Contract | App\Modules\AutonomousOperations\Application\Contracts\AutonomousOperationsContract |
| Module | app/Modules/AutonomousOperations/ |
| Allowed Dependencies | OI, Analytics contracts |
| Forbidden Dependencies | Mission/Agent internal services |
| Ownership | Autonomous Operations |
| Freeze | v3.2-autonomous-operations |
Assistant
| Responsibilities | Assistant registry, context assembly, assistant platform signals |
| Public Contract | App\Modules\Assistant\Application\Contracts\AssistantPlatformContract |
| Module | app/Modules/Assistant/ |
| Allowed Dependencies | AI Platform contracts (read) |
| Forbidden Dependencies | Agent/Mission internals |
| Ownership | Assistant Platform |
| Freeze | v3.3-assistant-platform |
Agent
| Responsibilities | Agent registry, orchestration preview, agent runtime signals |
| Public Contract | App\Modules\Agent\Application\Contracts\AgentPlatformContract |
| Module | app/Modules/Agent/ |
| Allowed Dependencies | AI Platform, Assistant contracts |
| Forbidden Dependencies | Mission internal engines |
| Ownership | Agent Platform |
| Freeze | v3.4-agent-platform |
Mission
| Responsibilities | Mission runtime, scheduling, state machine, mission types, control dashboard |
| Public Contract | App\Modules\Mission\Application\Contracts\MissionPlatformContract |
| Module | app/Modules/Mission/ |
| Allowed Dependencies | Agent, Assistant, OI, Analytics, Workflow (availability), Realtime contracts |
| Forbidden Dependencies | executeWorkflow from signal services; internal services of consumed platforms |
| Ownership | Mission Runtime |
| Freeze | v3.5-mission-runtime |
Deployment
| Responsibilities | Runtime configuration, environments, providers, secrets, feature flags, health checks |
| Public Contract | App\Modules\Deployment\Application\Contracts\DeploymentPlatformContract |
| Module | app/Modules/Deployment/ |
| Allowed Dependencies | Mission, Agent, Assistant, OI, Analytics, Workflow, Realtime contracts |
| Forbidden Dependencies | Observability/Production internals |
| Ownership | Deployment Platform |
| Freeze | v3.6-deployment-platform |
Observability
| Responsibilities | Log/audit/trace/alert/metric type registries, correlation, metrics, diagnostics, health timeline |
| Public Contract | App\Modules\Observability\Application\Contracts\ObservabilityPlatformContract |
| Module | app/Modules/Observability/ |
| Allowed Dependencies | Deployment, Mission, Agent, Assistant, OI, Analytics, Workflow, Realtime contracts |
| Forbidden Dependencies | Production internals; real logging backends |
| Ownership | Observability Platform |
| Freeze | v3.7-observability-platform |
Production
| Responsibilities | Security/authorization/rate-limit/retry/queue/cache/circuit-breaker/backup/recovery/readiness policies; production validation; readiness check types |
| Public Contract | App\Modules\Production\Application\Contracts\ProductionPlatformContract |
| Module | app/Modules/Production/ |
| Allowed Dependencies | Deployment, Observability, Mission, Agent, Assistant, OI, Analytics, Workflow, Realtime contracts |
| Forbidden Dependencies | All frozen platform internal services; infrastructure side effects |
| Ownership | Production Hardening |
| Freeze | v3.8-production-platform |
Growth
| Responsibilities | Scoring/opportunity/growth-signal/expansion policy registries; scoring model, opportunity, growth signal, and expansion signal type taxonomies; preview-safe scoring/opportunity/expansion/validation engines; growth evaluation context; read-only Growth Platform dashboard |
| Public Contract | App\Modules\Growth\Application\Contracts\GrowthPlatformContract |
| Module | app/Modules/Growth/ (platform layer under Application/) |
| Allowed Dependencies | EntitlementContract, LeadQueryServiceContract, AnalyticsAdvancedReadQueryContract, OperationalIntelligenceContract, AssistantPlatformContract, ProductionPlatformContract (availability only), ObservabilityPlatformContract |
| Forbidden Dependencies | CRM/Leads infrastructure; AI application services; frozen platform registries/engines/internal services; GrowthActionService; workflow/mission dispatch; lead mutations; campaign execution |
| Ownership | Growth Platform |
| Freeze | v3.9-growth-platform |
Compliance
| Responsibilities | Compliance rule, violation type, content scope type, and audit event type registries; compliance rule type taxonomy; preview-safe content scan, rule evaluation, and validation engines; compliance evaluation context; read-only Compliance Platform dashboard; legacy violation/audit actions remain in module |
| Public Contract | App\Modules\Compliance\Application\Contracts\CompliancePlatformContract |
| Module | app/Modules/Compliance/ (platform layer under Application/) |
| Allowed Dependencies | EntitlementContract, GrowthPlatformContract, AnalyticsAdvancedReadQueryContract, OperationalIntelligenceContract, AssistantPlatformContract, ProductionPlatformContract (availability only), ObservabilityPlatformContract |
| Forbidden Dependencies | CRM/Marketing infrastructure; frozen platform registries/engines/internal services; legacy ComplianceRuleEngine from platform layer; violation persistence from preview engines; content mutation; audit dispatch from previews |
| Ownership | Compliance Platform |
| Freeze | v3.10-compliance-platform |
Marketing
| Responsibilities | Marketing assets; asset graph; strategy layer; campaign policies; channel types; funnel policies; content policies; template types; platform knowledge; knowledge graph; recommendation engine; preview engines; validation; read-only Marketing Platform dashboard; legacy WhatsApp/content runtime remains in module |
| Public Contract | App\Modules\Marketing\Application\Contracts\MarketingPlatformContract |
| Module | app/Modules/Marketing/ (platform layer under Application/) |
| Allowed Dependencies | EntitlementContract, CompliancePlatformContract, GrowthPlatformContract, LeadQueryServiceContract, AnalyticsAdvancedReadQueryContract, OperationalIntelligenceContract, AssistantPlatformContract, ProductionPlatformContract (availability only), ObservabilityPlatformContract, ClinicQueryServiceContract |
| Forbidden Dependencies | Tracking internals; CRM writes; lead writes; campaign execution; WhatsApp execution; legacy Marketing runtime from platform layer; frozen platform registries/engines/internal services; lead mutations; content mutation from preview engines |
| Ownership | Marketing Platform |
| Freeze | v3.11-marketing-platform |
Tracking
| Responsibilities | Event taxonomy; event properties; attribution policies; source types; conversion policies; journey stages; privacy policies; integration types; tracking knowledge; event graph; attribution graph; recommendation engine; preview engines; validation; read-only Tracking Platform dashboard; legacy write runtime remains in module |
| Public Contract | App\Modules\Tracking\Application\Contracts\TrackingPlatformContract |
| Module | app/Modules/Tracking/ (platform layer under Application/) |
| Allowed Dependencies | EntitlementContract, MarketingPlatformContract, CompliancePlatformContract, GrowthPlatformContract, LeadQueryServiceContract, AnalyticsAdvancedReadQueryContract, OperationalIntelligenceContract, AssistantPlatformContract, ProductionPlatformContract (availability only), ObservabilityPlatformContract, ClinicQueryServiceContract |
| Forbidden Dependencies | TrackingFacade, TrackingService, Track*Action, Event model, Infrastructure imports, CRM writes, lead writes, frozen platform registries/engines/internal services, Analytics internal services, Marketing runtime execution, event persistence from preview engines |
| Ownership | Tracking Platform |
| Freeze | v3.12-tracking-platform |
Platform UX
| Responsibilities | Theme/token/component registries; action card and navigation card templates; structured response blocks; dashboard and report layout templates; feedback states; theme/token resolution; structured response composition; dashboard shell composition; report layout composition; locale/RTL presentation; accessibility metadata; deterministic layout recommendations; registry-driven Blade rendering; Filament theme provider; read-only Platform UX dashboard; legacy design tokens and per-platform dashboard Blade remain parallel |
| Public Contract | App\Modules\PlatformUX\Application\Contracts\PlatformUXPlatformContract, App\Modules\PlatformUX\Application\Contracts\DesignSystemContract, App\Modules\PlatformUX\Application\Contracts\PlatformUXPresentationContract |
| Module | app/Modules/PlatformUX/ |
| Allowed Dependencies | EntitlementContract, ClinicQueryServiceContract, ClinicTemplateViewService (read-only branding), ProductionPlatformContract (availability only), ObservabilityPlatformContract, GrowthPlatformContract, CompliancePlatformContract, MarketingPlatformContract, TrackingPlatformContract (availability signals only) |
| Forbidden Dependencies | CRM/Leads/Finance Infrastructure; frozen platform registries/engines/internal services; AI runtime; domain write Actions; Infrastructure models; direct config reads from consumer modules; business logic in Blade views |
| Ownership | Platform UX & Design System |
| Freeze | v4.1-platform-ux-design-system |
Public Experience
| Responsibilities | Public website orchestration; landing pages; website builder taxonomy; hero AI host surfaces; booking UX shells; navigation; SEO composition; content orchestration; QR experience; campaign pages; white-label theme bridge; visitor personalization; analytics hook plans; Platform UX composition delegation; journey context; deterministic recommendations; preview semantics; read-only Public Experience dashboard; contract-driven Filament builder shell; optional draft/publish persistence; public Blade presentation hosts; legacy ClinicTemplateSystem and static Blade remain parallel |
| Public Contract | App\Modules\PublicExperience\Application\Contracts\PublicExperiencePlatformContract, App\Modules\PublicExperience\Application\Contracts\PublicSurfaceContract |
| Module | app/Modules/PublicExperience/ |
| Allowed Dependencies | PlatformUXPlatformContract, DesignSystemContract, PlatformUXPresentationContract, EntitlementContract, ClinicQueryServiceContract, ClinicTemplateViewService (read-only), MarketingPlatformContract, TrackingPlatformContract, GrowthPlatformContract, CompliancePlatformContract, LeadQueryServiceContract, AnalyticsAdvancedReadQueryContract, CRM public read contracts (config allowlist), ProductionPlatformContract (availability only), ObservabilityPlatformContract, FinancialQueryContract (graceful degradation) |
| Forbidden Dependencies | CRM/Leads Infrastructure; ClinicTemplateSystem Infrastructure models; Platform UX internal registries/engines/resolvers; Marketing/Tracking legacy runtime Actions; AI Runtime SDKs; frozen platform internal services; domain write Actions from platform layer; business logic in composition engines, Filament pages, or Blade views |
| Ownership | Public Experience Platform |
| Freeze | v4.2-public-experience-platform |
Engineering Operating System
| Responsibilities | Engineering methodology; Cursor rules, skills, agents, commands; prompt library; templates; knowledge hierarchy; MCP governance documentation; architecture test integrity guards |
| Public Contract | N/A — documentation and engineering-test authority only; not a runtime module |
| Module | docs/development/, .cursor/ (engineering assets), tests/Architecture/GovernanceDocumentationTest.php, tests/Architecture/EngineeringOperatingSystemIntegrityTest.php |
| Allowed Dependencies | References to docs/architecture/, zaixos-company/ (cite), docs/product/, docs/releases/; must not restate governance text |
| Forbidden Dependencies | Runtime module modification; frozen platform code changes; MCP enablement without approval workflow; architecture approval by AI tools |
| Ownership | Engineering / Architect |
| Freeze | v5.0-ai-development-environment (provisional — confirmed at Git freeze) |
See docs/releases/v5.0-ai-development-environment.md.
Cross-Cutting Modules (Non-Platform)
| Module | Role | Public Surface |
|---|---|---|
| Shared | Kernel contracts, DTOs, clinic scoping | App\Modules\Shared\Application\Contracts\* |
| Clinic | Clinic configuration | ClinicQueryServiceContract |
| CRM | Patients, appointments, clinical workflows | Actions + FinancialQueryContract for finance reads |
| Leads | Lead capture, qualification | LeadQueryServiceContract, LeadCommandServiceContract |
| ClinicTemplateSystem | Website templating | ClinicTemplateViewService (public application service) |
Dependency Matrix (Platform Layers)
Higher layers may consume lower layers via contract only:
Public Experience → Platform UX / ClinicTemplateSystem / Marketing / Tracking / Compliance / Growth (contract-only reads)
Platform UX → Tracking / Marketing / Compliance / Growth (availability signals only)
Production → Observability → Deployment → Mission → Agent → Assistant
↓ ↓
Operational Intelligence → Advanced Analytics → Analytics
↓
Workflow (availability only) Realtime (presence)Never reverse dependencies. Never skip the public contract.
For freeze dates and commit hashes, see docs/releases/. For rules, see ARCHITECTURE_RULES.md.