Federated from workspace ·
PRD-001·Dental Clinic Revenue Operating System/docs/architecture/PUBLIC_API_CATALOG.mdDo not edit canonical truth here — update the source repo, then re-runnpm run docs:sync.
Public API Catalog
Cross-module surface area for Tier 1 core modules. 106 contracts exist platform-wide; 23 PublicApi gateways implement cross-module boundaries for Wave 2–4 recovery.
Rules
- Consumers import
Application/Contractsonly (plusApplication/DTOsfor data transfer). Application/PublicApiis for gateway implementations — consumers never import gateways.- One contract = one capability. No god interfaces (>15 methods requires ADR).
- Gateways delegate to internal services — not empty, not >8 internal delegates.
Saas
| Contract | Gateway | Capability |
|---|---|---|
ClinicTenantScopeContract | (TenantContext implements) | Read tenant clinic ID, scope flags |
ClinicTenantContextMutationContract | (TenantContext implements) | Bind/forget tenant context |
ClinicScopedIterationContract | ClinicScopedIterationGateway | Multi-clinic batch iteration |
EntitlementContract | (EntitlementService implements) | Feature gating |
Clinic
| Contract | Gateway | Capability |
|---|---|---|
ClinicTenantContextBindingContract | ClinicTenantContextBindingGateway | Bind session from clinic ID |
ClinicCurrencyFormatContract | ClinicCurrencyFormatGateway | Currency formatting |
ClinicPerformanceCacheContract | ClinicPerformanceCacheGateway | Dashboard/revenue cache |
ClinicIterationContract | ClinicIterationGateway | Active clinic ID iteration |
ClinicTenantQueryContract | ClinicTenantQueryGateway | Tenant clinic reads |
ClinicTenantCommandContract | ClinicTenantCommandGateway | Tenant clinic writes |
ClinicCustomerExperienceQueryContract | ClinicCustomerExperienceQueryGateway | CX aggregation reads |
ClinicServiceCatalogContract | (ClinicServiceCatalogService) | Service catalog |
ClinicIdentityQueryContract | (ClinicIdentityQueryService) | Clinic identity |
ClinicQueryServiceContract | (ClinicQueryService) | General clinic queries |
CRM
| Contract | Gateway | Methods | Notes |
|---|---|---|---|
CrmActionCommandContract | CrmActionCommandGateway | 10 | ⚠️ High method count — monitor |
CrmAuditCommandContract | CrmAuditCommandGateway | 2 | OK |
CrmIntelligenceQueryContract | CrmIntelligenceQueryGateway | 5 | OK |
CrmMetricsQueryContract | CrmMetricsQueryGateway | 3 | OK |
CrmSchedulingQueryContract | CrmSchedulingQueryGateway | 3 | OK |
CrmEntityAccessContract | CrmEntityAccessGateway | 6 | ⚠️ Returns infra models internally |
CrmLeadProfileQueryContract | CrmLeadProfileQueryGateway | 1 | ⚠️ Model leakage in return array |
CrmLeadTimelineEnrichmentContract | CrmLeadTimelineEnrichmentGateway | 5 | ⚠️ Model leakage |
CrmUsageMetricsContract | CrmUsageMetricsGateway | 5 | ⚠️ Model queries |
CrmCustomerExperienceQueryContract | CrmCustomerExperienceQueryGateway | 1 | OK |
FinancialQueryContract | (FinancialQueryService) | — | Saas/CRM billing reads |
ReminderDeliveryProvider | (internal) | — | CRM-internal port |
Leads
| Contract | Implementer | Capability |
|---|---|---|
LeadEntityContract | Lead model adapter | Lead identity without infra import |
LeadAccessContract | LeadAccessService | Scoped lead lookup |
LeadTimelineContract | LeadTimelineService | Timeline writes |
LeadCommandServiceContract | LeadCommandService | Lead mutations |
LeadQueryServiceContract | LeadQueryService | Lead reads |
Compliance
| Contract | Implementer | Capability |
|---|---|---|
ComplianceAuditContract | AuditLogService | Cross-module audit writes |
ComplianceAuditQueryContract | ComplianceAuditQueryService | Audit feed reads |
OperationalEventContextFactoryContract | OperationalEventContextFactory | Event metadata envelope |
Workspace
| Contract | Implementer | Capability |
|---|---|---|
WorkspaceNotificationDispatchContract | NotificationService | Staff/external notifications |
WorkspaceQueryContract | WorkspaceQueryService | Workspace reads |
NotificationInboxContract | SharedNotificationInboxProvider | Inbox surface |
Realtime
| Contract | Gateway | Capability |
|---|---|---|
InAppNotificationPublishContract | InAppNotificationPublishGateway | Realtime fan-out for in-app notifications |
RealtimePlatformContract | RealtimePlatformService | Platform publish API |
ClinicTemplateSystem
| Contract | Gateway | Capability |
|---|---|---|
ClinicTemplateBrandingCommandContract | ClinicTemplateBrandingCommandGateway | Branding updates |
ClinicTemplateOnboardingCommandContract | ClinicTemplateOnboardingCommandGateway | Onboarding provisioning |
ClinicTemplateCustomerExperienceQueryContract | ClinicTemplateCustomerExperienceQueryGateway | CX reads |
ClinicTemplateUsageMetricsContract | ClinicTemplateUsageMetricsGateway | Usage metering |
ClinicTemplateScheduleQueryContract | (internal service) | CRM scheduling reads |
Shared Kernel Contracts
| Contract | Implementation module |
|---|---|
ClinicConfigurationContract | ClinicTemplateSystem |
BackupHandlerContract | Production |
TenantConnectionResolverContract | Saas |
Workspace Contracts
| Contract | Gateway / Implementation |
|---|---|
NotificationChannelHandlerContract | Workspace channel handlers (EmailNotificationChannel, etc.) |
Future Split Recommendations (report only — do not refactor now)
| Contract | Issue | Suggested split |
|---|---|---|
CrmActionCommandContract | 10 commands in one surface | Split into CrmAppointmentCommandContract, CrmInvoiceCommandContract, CrmLeadCommandContract |
CrmEntityAccessGateway | Returns Eloquent models | Return DTO snapshots; keep gateway as anti-corruption layer |
CrmLeadProfileQueryGateway | Array of infra models | CrmLeadProfileSnapshot DTO |
MarketingPlatformContract | 24 methods | Already platform-style; acceptable with freeze policy |
Growth → CRM Services | Direct service imports | CrmGrowthMetricsContract gateway |