# Domains, routing, and Filament panels

## Domain records

The central `domains` table is represented by `TenantDomain` and contains:

- `tenant_id`
- normalized `domain`
- `type` (`subdomain` or `custom`)
- `is_primary`
- `verification_status`
- `verification_token_hash` (never exposed)
- `verified_at`
- `ssl_status`
- `last_checked_at`

`TenantDomainStatus` supports `pending`, `verified`, `active`, `failed`, and `suspended`.

## Platform subdomains

Tenant creation reserves the slug. Store access becomes available after unified-schema initialization and first-admin activation. The platform domain comes from `TENANCY_PLATFORM_DOMAIN` and is normalized to a host.

Reserved host prefixes are `www`, `console`, `admin`, `api`, `mail`, `support`, and `status`.

## Custom domains

Use `TenantDomainService::addCustomDomain()` instead of creating a domain row directly. It normalizes the host, rejects invalid/reserved/duplicate domains, and returns the one-time plaintext verification token while storing only its hash.

Verification options:

```bash
# Verify a token directly (useful for controlled tests).
php artisan tenant:domain:verify <domain-record-id> <token>

# Verify the TXT record at _matjari-verification.<domain>.
php artisan tenant:domain:verify <domain-record-id> <token> --dns

# Queue DNS verification with retries/backoff.
php artisan tenant:domain:verify <domain-record-id> <token> --dns --queue
```

The TXT record is:

```text
name:  _matjari-verification.example.com
type:  TXT
value: <token>
```

Only verified/active domains can become primary. `setPrimary()` locks the selected domain and all sibling domains in one central transaction, so there is never more than one primary domain per tenant.

SSL certificates and edge routing are managed by the hosting/CDN layer; the application records the status through `TenantDomainService::updateSslStatus()`.

## Request middleware

The store panel middleware order is significant:

1. `PreventAccessFromCentralDomains` rejects central hosts.
2. `InitializeTenancyByDomainOrSubdomain` resolves the tenant from the host.
3. `EnsureVerifiedTenantDomain` requires a verified/active matching domain.
4. `EnsureActiveTenant` rejects provisioning, pending-admin, suspended, failed, and archived stores.
5. `EnsureStoreFeatureForRequest` blocks disabled resource paths.
6. `UseStoreSessionCookie` selects the store-specific session cookie.
7. `EnforceTenantSession` binds database sessions to the resolved tenant and rejects cross-tenant reuse.

The central `/admin` and `/console` panels use `EnsureCentralDomain`, which normalizes casing and trailing dots before comparison.

Unknown, unverified, suspended, or archived domains return 404 rather than revealing tenant existence.

## Filament panels

| Panel | URL | Guard/model | Purpose |
| --- | --- | --- | --- |
| Admin | `/admin` | `company_admin` / `CompanyAdmin` | Company administration. |
| Console | `/console` | `company_admin` / `CompanyAdmin` | Company tenant-management console. |
| Store | `/store` | `store_admin` / `Admin` | Tenant business resources. |

The Console panel contains tenant resources, domains/features/provisioning relation managers, lifecycle actions, Shield authorization, activity logging, and Matjari branding. It must not contain tenant business resources.

The Store panel contains tenant business resources and excludes central tenant-management resources. Feature-dependent resource navigation and relation-manager tabs are hidden when a feature is disabled, while request middleware still rejects direct access.

## Adding a new tenant resource

1. Put its migration under `database/migrations/tenant` and include it in unified ownership migration coverage.
2. Register its model with `TenantOwnedScope`.
3. Register it in `StorePanelProvider`, not the Console panel.
4. Add a `StoreFeature` mapping if optional.
5. Add the route key to `EnsureStoreFeatureForRequest` if the feature is optional.
6. Use localized Filament labels, sections, one-column root schemas, and distinct icons.
7. Add tenant isolation and feature-disabled tests.

Use tenant context and the ownership scope instead of accepting a tenant ID from request input.
