Platform Module Technical Specifications

Three-layer adapter system:

RestoreService ↕ delegates to pitrRegistry.get() → PgBackRestAdapter | ExternalPitrAdapter ↕ (PgBackRestAdapter uses) ↕ (ExternalPitrAdapter uses) SidecarRestoreManager → sidecar Postgres process → pg_dump | psql merge pipeline → selective table extract at specific timestamp

PgBackRestAdapter:

• Uses pgbackrest CLI for backup/restore
• Requires stanza to be created + configured
• Honest no-op: { enabled: false, reason: "stanza_not_created" } when not configured
• Integrates SidecarRestoreManager for selective extract

ExternalPitrAdapter:

• For customer-managed Postgres scenarios
• AEGIS_PITR_ADAPTER=external opts into this adapter
• Same API surface as PgBackRestAdapter

SidecarRestoreManager:

```typescript class SidecarRestoreManager { // Selective extract pipeline: // 1. Start sidecar Postgres process // 2. pg_dump with --table and --timestamp filters // 3. psql merge into target tenant DB // 4. Shutdown sidecar process

extractTablesAtTime( tables: string[], timestamp: Date, targetTenantId: string, ): Promise<void>; } ```

BulkUndoService: Event-store based. Read-only until operator calls bulkUndo.execute(). No side effects on registration. For reverting mass data corruption events.

The SOC2 problem: "Untested backups are not backups." A backup that has never been restored is a liability — when you need it, you might find it's corrupt, incomplete, or incompatible with your current schema.

BackupVerificationService:

typescript // Runs weekly per tenant (also available as a manual run) async runVerification(ctx, options?: { tenantId?, manualRun? }): Promise<VerificationRunResult> // 1. Check eligibility (skip if not due, or no backup to verify yet) // 2. Find the most recent successful backup // 3. Restore it and run integrity checks against the restored data // 4. Record the run and emit aegis.verification.{passed,failed,skipped}

ComplianceReportService:

typescript // Runs monthly per tenant (also available as a manual run) async generateReport(ctx, tenantId): Promise<ComplianceReport> // 1. Roll up all backup + verification activity for the period // 2. Format as auditor-facing JSON + HTML // 3. Upload to BYOB S3 alongside backups // 4. Report includes: verification pass counts, retention compliance, artifacts

Rather than routing through a third-party ESP, MailService provisions a real mail server (Postfix + Dovecot + OpenDKIM) directly on the customer's own VPS instance over SSH — so hosted mailboxes live on infrastructure the tenant already owns.

```typescript // Configure Postfix + Dovecot + OpenDKIM for a domain on the tenant's VPS. // Generates DKIM keys, writes the OpenDKIM/Postfix/Dovecot config over SSH, // restarts the mail services, and returns the DKIM public key for DNS. async configureMail(ctx, tenantId, domain): Promise<{ dkimPublicKey: string }>

// Create a mailbox on the tenant's VPS (bcrypt-hashed password via Dovecot). async createMailbox(ctx, tenantId, email, password, displayName?, linkedUserId?, visibility?)

// Verify a domain's MX / SPF / DKIM / DMARC DNS records before enabling mail. async verifyEmailDns(ctx, domain): Promise<{ spf: { status: string; record: string }; dkim: { status: string; record: string }; dmarc: { status: string; record: string }; }> ```

Mailboxes created this way auto-connect to the Inbox module, so hosted mail shows up alongside the tenant's other conversations without a separate IMAP integration step.

```typescript // Subscription states: trial | active | past_due | cancelled | suspended

// Upgrade: immediate entitlement grant upgradePlan(subscriptionId, newPlanId) { → subscriptionService.updateById({ plan: newPlanId }) → grantEntitlements(tenantId, plan.entitlements, plan.tier) → emit platform.subscription.upgraded }

// Cancel (end of period): flag set, no immediate action cancelSubscription(subscriptionId, immediately = false) → if immediately: status → cancelled, provisioning job → "suspend" → else: cancelAtPeriodEnd → true

// Cancel (immediately): suspends instances to stop billing // Cancel (end of period): billing stops at period end, instances suspended then

// Reactivate: clears flags, resumes suspended instances reactivate(subscriptionId) → status → active, cancelAtPeriodEnd → false, cancelledAt → null → list suspended instances → create "resume_instance" jobs

// Payment webhooks (from Billing module) handlePaymentSuccess(providerSubscriptionId) → Update period dates → Clear pastDueSince

handlePaymentFailure(providerSubscriptionId) → past_due status → Emit notification event → dunning sequence starts ```

Trial expiry cron: Daily cron checks for expired trials. Expired trial → status: "cancelled", notification sent to tenant.

Each Realtime tier (starter / standard / pro / enterprise) needs a different class of VPS to run its real-time workload — Enterprise's 500-participant webinar mode pushes the LiveKit subprocess's RAM usage well past what a smaller box can hold alongside the rest of the stack. Rather than making tenants manually resize their own server, the service reacts to subscription changes and resizes the underlying VPS to match.

```typescript type RealtimeTier = "starter" | "standard" | "pro" | "enterprise";

// Subscribed to billing.subscription.upgraded / billing.subscription.downgraded. async handleTierChange(ctx, tenantId, fromTier, toTier): Promise<{ resized: boolean; reason?: string; }> ```

Flow:

1. On a tier change event, look up the tenant's active instance and VPS provider
2. Map the new tier to that provider's server type (e.g., Hetzner CX32 → CX42 for Enterprise) — different tiers that land on the same VPS class are a no-op
3. Upgrades resize immediately, then email the tenant confirming the new server size; if the resize fails partway, a separate email tells them the subscription is active but the VPS upgrade needs support to finish
4. Downgrades are deferred — scheduled for an off-peak cron run after a 7-day grace period, with a heads-up email sent immediately and another right before the resize happens

This keeps subscription changes from causing behind-the-scenes VPS resize churn on every plan click, while still making sure a tenant's server can actually handle the tier they've paid for.