Tenant Domain Architecture

1. Overview — 5 zones, 2 access patterns

V4 chia domain thành 5 zones. Tenant operations có 2 cách access song song.

2. Domain Zones — Chi tiết

5 zones độc lập, mỗi zone có purpose rõ.

3. Resolution Logic — Request → Tenant

Request đến, backend Laravel middleware resolve tenant qua Host header.

Laravel middleware logic (pseudocode)

// app/Http/Middleware/IdentifyTenant.php
class IdentifyTenant {
  public function handle(Request $request, Closure $next) {
    $host = $request->getHost();                       // e.g., "factory-abc.viecxanh.vn"
    $tenant = null;

    // 1. Reserved domains — no tenant
    if (in_array($host, ['viecxanh.vn', 'api.viecxanh.vn', 'system.viecxanh.vn', 'ai.viecxanh.vn'])) {
      // Try extract tenant from JWT claim or X-Tenant-Slug header
      $tenantId = auth()->user()?->current_tenant_id
               ?? Tenant::where('slug', $request->header('X-Tenant-Slug'))->first()?->id;
      if ($tenantId) $tenant = Tenant::find($tenantId);
      return $this->setContext($tenant, $next, $request);
    }

    // 2. Subdomain pattern: {slug}.viecxanh.vn
    if (str_ends_with($host, '.viecxanh.vn')) {
      $slug = explode('.', $host)[0];
      $tenant = Tenant::where('slug', $slug)->first();
      if (!$tenant) abort(404, 'Tenant không tồn tại');
      return $this->setContext($tenant, $next, $request);
    }

    // 3. Custom domain lookup
    $tenant = Tenant::where('custom_domain', $host)
      ->whereNotNull('custom_domain_verified_at')
      ->first();
    if (!$tenant) abort(404, 'Domain chưa được cấu hình');
    return $this->setContext($tenant, $next, $request);
  }

  private function setContext($tenant, $next, $request) {
    if ($tenant) {
      app()->instance('current_tenant', $tenant);
      // Set PG session var for RLS policies
      DB::statement("SET app.current_tenant_id = ?", [$tenant->id]);
    }
    return $next($request);
  }
}

4. Schema Changes — tenants table

Thêm 3 columns để hỗ trợ custom domain.

ALTER TABLE tenants
  ADD COLUMN custom_domain VARCHAR(255) UNIQUE,                 -- e.g., 'abc.com.vn'
  ADD COLUMN custom_domain_verified_at TIMESTAMPTZ,             -- DNS TXT verified
  ADD COLUMN custom_domain_ssl_status VARCHAR(20)                -- pending|active|expired|failed
    CHECK (custom_domain_ssl_status IN ('pending','active','expired','failed')),
  ADD COLUMN custom_domain_verification_token VARCHAR(64);        -- DNS TXT value

-- Index for fast custom domain lookup
CREATE UNIQUE INDEX idx_tenants_custom_domain
  ON tenants(custom_domain)
  WHERE custom_domain_verified_at IS NOT NULL;

-- Optional: SSL cert storage
CREATE TABLE tenant_ssl_certificates (
  id BIGSERIAL PRIMARY KEY,
  tenant_id BIGINT NOT NULL REFERENCES tenants(id),
  domain VARCHAR(255) NOT NULL,
  certificate TEXT,                                    -- PEM encoded
  private_key TEXT,                                    -- encrypted
  issued_at TIMESTAMPTZ,
  expires_at TIMESTAMPTZ,
  auto_renew BOOLEAN DEFAULT true,
  status VARCHAR(20)
);

Model relationships

5. Custom Domain Onboarding Flow

Tenant từ subdomain-only → thêm custom domain trong 3 phase: add → verify → SSL → activate.

Phase 1: Add Domain (Tenant admin action)

1. Tenant admin vào factory-abc.viecxanh.vn/admin/settings/domains
2. Click "Thêm custom domain" → nhập abc.com.vn
3. System generate random verification token (64 chars) → lưu vào custom_domain_verification_token
4. System hiển thị cho tenant admin:

   DNS TXT record to add at your DNS provider:
   
     Name:  _viecxanh-verify.abc.com.vn
     Type:  TXT
     Value: vx4-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
     TTL:   300

Phase 2: DNS Verification (Async)

1. Tenant thêm TXT record vào DNS provider của họ (Cloudflare, Route53, etc.)
2. Tenant click "Verify now" trên admin UI (hoặc system auto-check mỗi 5 phút)
3. System thực hiện DNS lookup:

   dig TXT _viecxanh-verify.abc.com.vn +short
   # Compare with stored token

4. Nếu match → set custom_domain_verified_at = NOW()
5. Send email "Domain verified" to tenant admin

Phase 3: SSL Provision (Automatic)

1. System trigger SSL job via Let's Encrypt ACME client (certbot hoặc acme.sh)
2. HTTP-01 challenge: system serve /.well-known/acme-challenge/... trên abc.com.vn
3. Tenant đã point A record abc.com.vn → viecxanh server IP
4. Let's Encrypt validate → issue cert
5. Cert stored trong tenant_ssl_certificates table, nginx reload
6. Set custom_domain_ssl_status = 'active'
7. Email "SSL active — your domain is live" to tenant admin

Phase 4: Auto-renewal

1. Scheduled job daily: check cert expiry
2. If expires < 30 days → trigger ACME renew
3. On renew success → reload nginx, update DB
4. On renew fail → alert tenant admin + ops team

6. UX Flows — Per User Type

Trải nghiệm thực tế cho từng loại user.

Staff Admin (của tenant)

Worker (cross-tenant identity)

Employer User (multi-tenant capable)

Super Admin (ViệcXanh ops)

7. Tiers — Basic vs Premium

Dual-domain support cho phép tier pricing rõ ràng.

Tenant có thể đổi tier bất kỳ lúc nào

8. Infrastructure Requirements

DNS, SSL, monitoring setup (không chi tiết config — đó là việc sau).