# Navi Provider Integration Control Tower

## Purpose

The Provider Integration Control Tower is the admin foundation for showing broad Navi service categories while keeping operational readiness explicit. A category can be marketed before it is live, and each third-party provider integration is configured with a safe environment, readiness state, vault reference, health status, and audit trail.

## Category Operating Modes

| Mode | Meaning | Customer impact |
| --- | --- | --- |
| `DISABLED` | Category is not available. | Hide or show unavailable state. |
| `MARKETING_ONLY` | Category can be used for GTM and partner acquisition only. | No transactional CTA. |
| `INQUIRY_ONLY` | Users can submit interest or contact requests. | No confirmed booking/payment. |
| `DEMO_ONLY` | Demo data may be shown in isolated demo environments. | Never production-confirmed. |
| `SANDBOX_READY` | Provider sandbox exists and can be tested. | Not live transaction ready. |
| `LIVE_READY` | Category is approved for production operations. | Live actions may be enabled by API rules. |

These modes are product and marketing controls. A live category alone does not make a provider live; production actions also require provider-level environment, readiness, health, and vault-reference checks.

## Provider Integration Model

The API stores provider configuration in `ProviderIntegration`:

- Provider name
- Provider category
- Environment: `DEMO`, `SANDBOX`, `PRODUCTION`
- API base URL
- Webhook URL
- Vault secret reference name
- Enabled flags for booking, payment, refund, commission, inquiry, sandbox, and live readiness
- Health status, last check, last sync, and error message
- Creator/updater user references
- Shared safety warnings returned to the dashboard for operator clarity

Raw provider API secrets are not part of the model. The database stores only vault reference names such as `doppler/navi/provider/foo`.

## Safety Rules

The shared provider-control validator layer defines the readiness checks used by the API and dashboard. Current blocking rules are:

- Production providers cannot be enabled, live-ready, booking-enabled, payment-enabled, refund-enabled, or commission-enabled without `vaultSecretRef`.
- Production providers cannot be marked live ready while health is `DEGRADED`, `DOWN`, or `DISABLED`.
- A live-ready production provider must also be enabled.
- Demo providers cannot be marked live ready.
- Demo providers cannot have payment, refund, or commission enabled.
- Refund and commission flags require payment to be enabled.
- Payment-enabled providers require a vault reference.
- Sandbox payment providers require `sandboxReady`.
- Production payment providers require `liveReady`.

The dashboard also displays non-blocking readiness labels:

- Demo only
- Sandbox ready
- Production live
- Missing vault reference
- Booking disabled
- Payment disabled
- Refund disabled
- Commission disabled
- Health not verified

## RBAC

Management requires one of:

- `provider_integration.write`
- `admin.provider.write`
- `superadmin.integration.manage`

Read access for full settings requires one of:

- `provider_integration.read.all`
- `admin.provider.read`
- `superadmin.integration.manage`

Support health visibility is narrower and uses:

- `provider_integration.health.read`
- `audit.read.support`

Partner users must not receive global provider integration permissions.

## Audit

The API writes `AuditLog` rows for:

- Category mode changes
- Provider integration creation
- Provider integration updates
- Provider integration disable actions
- Provider mock health checks

Audit resource types are `category_mode` and `provider_integration`.

The dashboard Provider Audit History page reads this audit stream as a read-only timeline. The Provider Integrations page also shows recent audit entries inline on each integration when the operator has audit read permission. Operators can inspect before and after snapshots, but cannot mutate provider state from audit views.

## Current Foundation vs Future Work

Current foundation is real database-backed admin configuration with RBAC, shared validators, shared types, shared API-client endpoints, safety warnings, and audit logs. Provider health checks are intentionally safe and mocked; no external provider API is called in this wave.

Future provider adapters can replace the mock health check only after contracts, sandbox credentials, webhook verification, rollback plans, and vault integration are approved.