docs: add system architecture documentation

app/api/plesk/instances/[id]/backfill-domain-links/route.ts

@@ -1,51 +0,0 @@
-import { NextResponse } from "next/server";
-
-import { assertAgencyAdmin, getRouteAgencyContextOrThrow } from "@/lib/agency";
-import { assertRateLimit } from "@/lib/api/rate-limit";
-import { assertSameOrigin } from "@/lib/api/security";
-import { backfillDomainSubscriptionLinks } from "@/lib/plesk/sync";
-import { createSupabaseRouteClient } from "@/lib/supabase/route";
-
-export async function POST(
-  req: Request,
-  { params }: { params: { id: string } },
-) {
-  try {
-    assertSameOrigin(req);
-
-    const context = await getRouteAgencyContextOrThrow();
-    assertAgencyAdmin(context);
-    assertRateLimit(`plesk-backfill-links:${context.userId}`, 5, 60_000);
-
-    const supabase = createSupabaseRouteClient() as any;
-
-    const { data: instance, error: instanceError } = await supabase
-      .from("plesk_instances")
-      .select("id")
-      .eq("id", params.id)
-      .eq("agency_id", context.agencyId)
-      .single();
-
-    if (instanceError || !instance) {
-      throw new Error("Plesk instance not found");
-    }
-
-    const result = await backfillDomainSubscriptionLinks(supabase, {
-      agencyId: context.agencyId,
-      instanceId: params.id,
-      actorUserId: context.userId,
-    });
-
-    return NextResponse.json({ ok: true, ...result });
-  } catch (error) {
-    return NextResponse.json(
-      {
-        error:
-          error instanceof Error
-            ? error.message
-            : "Backfill domain links failed",
-      },
-      { status: 400 },
-    );
-  }
-}

app/api/plesk/subscriptions/[id]/action/route.ts

@@ -5,8 +5,6 @@ import { assertAgencyAdmin, getRouteAgencyContextOrThrow } from "@/lib/agency";
 import { assertRateLimit } from "@/lib/api/rate-limit";
 import { assertSameOrigin } from "@/lib/api/security";
 import {
-  parseSubscriptionStatusDetailsFromInfo,
-  pleskCliCall,
   suspendPleskSubscription,
   unsuspendPleskSubscription,
 } from "@/lib/plesk/client";
@@ -82,59 +80,12 @@ export async function POST(
       );
     }
 
-    const fallbackStatus =
-      payload.action === "suspend" ? "suspended" : "active";
-    let refreshedStatus = fallbackStatus;
-    let refreshedStatusRaw: string | null = null;
-    let refreshErrorMessage: string | null = null;
-
-    try {
-      const infoResult = await pleskCliCall(connection, "subscription", [
-        "--info",
-        subscription.plesk_subscription_id,
-      ]);
-      const parsed = parseSubscriptionStatusDetailsFromInfo(
-        infoResult.stdout ?? "",
-      );
-      refreshedStatus = parsed.status;
-      refreshedStatusRaw = parsed.statusRaw;
-    } catch (refreshError) {
-      refreshErrorMessage =
-        refreshError instanceof Error
-          ? refreshError.message.slice(0, 1000)
-          : "subscription_status_refresh_failed";
-
-      await supabase.from("actions_log").insert({
-        agency_id: context.agencyId,
-        actor_user_id: context.userId,
-        target_type: "plesk_subscription",
-        target_id: subscription.id,
-        action: "subscription_status_refresh_failed",
-        status: "failed",
-        error_message: refreshErrorMessage,
-        metadata: {
-          subscription_id: subscription.id,
-          plesk_subscription_id: subscription.plesk_subscription_id,
-          plesk_instance_id: subscription.plesk_instance_id,
-        },
-      });
-    }
-
+    const newStatus = payload.action === "suspend" ? "suspended" : "active";
     const { error: updateError } = await supabase
       .from("plesk_subscriptions")
-      .update({
-        status: refreshedStatus,
-        status_raw: refreshedStatusRaw,
-        last_status_sync_at: new Date().toISOString(),
-      })
+      .update({ status: newStatus })
       .eq("id", subscription.id);
 
-    await supabase
-      .from("plesk_domains")
-      .update({ status: refreshedStatus })
-      .eq("agency_id", context.agencyId)
-      .eq("subscription_id", subscription.id);
-
     await supabase.from("actions_log").insert({
       agency_id: context.agencyId,
       actor_user_id: context.userId,
@@ -144,17 +95,14 @@ export async function POST(
       status: "success",
       metadata: {
         plesk_subscription_id: subscription.plesk_subscription_id,
-        refreshed_status: refreshedStatus,
-        refresh_error: refreshErrorMessage,
         db_status_update_error: updateError?.message ?? null,
       },
     });
 
     return NextResponse.json({
       ok: true,
-      status: refreshedStatus,
+      status: newStatus,
       dbStatusUpdated: !updateError,
-      refreshError: refreshErrorMessage,
     });
   } catch (error) {
     if (supabase && context && subscription) {

app/dashboard/page.tsx

@@ -17,26 +17,6 @@ type ActionLogSummary = Pick<
   "target_id" | "status" | "action" | "created_at" | "error_message"
 >;
 
-function normalizeDomainLike(value: string) {
-  return value.trim().toLowerCase().replace(/\.$/, "");
-}
-
-function findBestSuffixStatusMatch(
-  normalizedDomain: string,
-  candidates: Array<{ normalizedName: string; status: string | null }>,
-) {
-  let best: { normalizedName: string; status: string | null } | null = null;
-
-  for (const candidate of candidates) {
-    if (!normalizedDomain.endsWith(`.${candidate.normalizedName}`)) continue;
-    if (!best || candidate.normalizedName.length > best.normalizedName.length) {
-      best = candidate;
-    }
-  }
-
-  return best?.status ?? null;
-}
-
 export default async function DashboardPage() {
   const context = await getServerAgencyContextOrRedirect();
   const supabase = createSupabaseServerClient() as any;
@@ -70,7 +50,7 @@ export default async function DashboardPage() {
     supabase
       .from("plesk_domains")
       .select(
-        "id, plesk_instance_id, subscription_id, external_subscription_id, status, domain_name, hosting_type, source_created_at, aliases_count, updated_at",
+        "id, plesk_instance_id, subscription_id, domain_name, status, hosting_type, source_created_at, aliases_count, updated_at",
       )
       .eq("agency_id", context.agencyId)
       .order("updated_at", { ascending: false })
@@ -121,7 +101,6 @@ export default async function DashboardPage() {
         id: string;
         plesk_instance_id: string;
         subscription_id: string | null;
-        external_subscription_id: string | null;
         domain_name: string;
         status: string | null;
         hosting_type: string | null;
@@ -134,69 +113,6 @@ export default async function DashboardPage() {
     { data: ActionLogSummary[] | null },
   ];
 
-  const domainInstanceIds = Array.from(
-    new Set((domains ?? []).map((domain) => domain.plesk_instance_id)),
-  );
-
-  const { data: domainSubscriptions } =
-    domainInstanceIds.length > 0
-      ? await supabase
-          .from("plesk_subscriptions")
-          .select("id, plesk_instance_id, plesk_subscription_id, name, status")
-          .eq("agency_id", context.agencyId)
-          .in("plesk_instance_id", domainInstanceIds)
-      : { data: [] };
-
-  const subscriptionStatusById = new Map<string, string | null>(
-    (domainSubscriptions ?? []).map((subscription: any) => [
-      String(subscription.id),
-      subscription?.status ? String(subscription.status) : null,
-    ]),
-  );
-
-  const subscriptionStatusByExternalId = new Map<string, string | null>(
-    (domainSubscriptions ?? [])
-      .filter((subscription: any) =>
-        Boolean(
-          subscription?.plesk_instance_id &&
-          subscription?.plesk_subscription_id,
-        ),
-      )
-      .map((subscription: any) => [
-        `${String(subscription.plesk_instance_id)}:${String(subscription.plesk_subscription_id)}`,
-        subscription?.status ? String(subscription.status) : null,
-      ]),
-  );
-
-  const subscriptionStatusByInstanceAndName = new Map<string, string | null>(
-    (domainSubscriptions ?? [])
-      .filter((subscription: any) =>
-        Boolean(subscription?.plesk_instance_id && subscription?.name),
-      )
-      .map((subscription: any) => [
-        `${String(subscription.plesk_instance_id)}:${normalizeDomainLike(String(subscription.name))}`,
-        subscription?.status ? String(subscription.status) : null,
-      ]),
-  );
-
-  const subscriptionStatusNameCandidatesByInstance = new Map<
-    string,
-    Array<{ normalizedName: string; status: string | null }>
-  >();
-
-  for (const subscription of domainSubscriptions ?? []) {
-    if (!subscription?.plesk_instance_id || !subscription?.name) continue;
-
-    const instanceId = String(subscription.plesk_instance_id);
-    const existing =
-      subscriptionStatusNameCandidatesByInstance.get(instanceId) ?? [];
-    existing.push({
-      normalizedName: normalizeDomainLike(String(subscription.name)),
-      status: subscription?.status ? String(subscription.status) : null,
-    });
-    subscriptionStatusNameCandidatesByInstance.set(instanceId, existing);
-  }
-
   const autoSyncByInstance = new Map<
     string,
     { status: string; created_at: string; error_message: string | null }
@@ -251,35 +167,7 @@ export default async function DashboardPage() {
       <DashboardControls
         instances={instances ?? []}
         subscriptions={subscriptions ?? []}
-        domains={(domains ?? []).map((domain) => {
-          const joinedStatusByLocalId = domain.subscription_id
-            ? subscriptionStatusById.get(domain.subscription_id)
-            : null;
-          const joinedStatusByExternalId = domain.external_subscription_id
-            ? subscriptionStatusByExternalId.get(
-                `${domain.plesk_instance_id}:${domain.external_subscription_id}`,
-              )
-            : null;
-          const joinedStatusByName = subscriptionStatusByInstanceAndName.get(
-            `${domain.plesk_instance_id}:${normalizeDomainLike(domain.domain_name)}`,
-          );
-          const joinedStatusBySuffix = findBestSuffixStatusMatch(
-            normalizeDomainLike(domain.domain_name),
-            subscriptionStatusNameCandidatesByInstance.get(
-              domain.plesk_instance_id,
-            ) ?? [],
-          );
-          const joinedStatus =
-            joinedStatusByLocalId ??
-            joinedStatusByExternalId ??
-            joinedStatusByName ??
-            joinedStatusBySuffix;
-
-          return {
-            ...domain,
-            status: joinedStatus ?? "unknown",
-          };
-        })}
+        domains={domains ?? []}
         autoSyncByInstance={Object.fromEntries(autoSyncByInstance.entries())}
       />
     </main>

lib/plesk/sync.ts

@@ -22,34 +22,8 @@ type InstanceRow = Pick<
   | "last_connected_at"
 >;
 
-type LocalSubscriptionLookupRow = {
-  id: string;
-  plesk_subscription_id: string;
-  name: string | null;
-  status: string | null;
-};
-
 const MIN_INTERVAL_MS = 3 * 60 * 1000;
 
-function normalizeDomainLike(value: string) {
-  return value.trim().toLowerCase().replace(/\.$/, "");
-}
-
-function findBestSuffixSubscriptionMatch<
-  T extends { normalizedName: string; id: string; status: string | null },
->(normalizedDomain: string, candidates: T[]) {
-  let best: T | undefined;
-
-  for (const candidate of candidates) {
-    if (!normalizedDomain.endsWith(`.${candidate.normalizedName}`)) continue;
-    if (!best || candidate.normalizedName.length > best.normalizedName.length) {
-      best = candidate;
-    }
-  }
-
-  return best;
-}
-
 export async function syncPleskInstance(
   supabase: SupabaseLike,
   instance: InstanceRow,
@@ -182,7 +156,7 @@ export async function syncPleskInstance(
     const { data: localSubscriptions, error: localSubscriptionsError } =
       await supabase
         .from("plesk_subscriptions")
-        .select("id, plesk_subscription_id, name, status")
+        .select("id, plesk_subscription_id, status")
         .eq("agency_id", instance.agency_id)
         .eq("plesk_instance_id", instance.id);
 
@@ -190,116 +164,33 @@ export async function syncPleskInstance(
       throw new Error(localSubscriptionsError.message);
     }
 
-    const subscriptionsIndexed = ((localSubscriptions ?? []) as Array<any>)
-      .filter((row): row is LocalSubscriptionLookupRow =>
-        Boolean(row?.plesk_subscription_id && row?.id),
-      )
-      .map((row) => ({
-        id: String(row.id),
-        pleskSubscriptionId: String(row.plesk_subscription_id),
-        status: row?.status ? String(row.status) : null,
-        name: row?.name ? String(row.name) : null,
-      }));
-
     const subscriptionByExternalId = new Map<
       string,
-      {
-        id: string;
-        pleskSubscriptionId: string;
-        status: string | null;
-        name: string | null;
-      }
-    >(subscriptionsIndexed.map((row) => [row.pleskSubscriptionId, row]));
-
-    const subscriptionByLocalId = new Map<
-      string,
-      {
-        id: string;
-        pleskSubscriptionId: string;
-        status: string | null;
-        name: string | null;
-      }
-    >(subscriptionsIndexed.map((row) => [row.id, row]));
-
-    const subscriptionByName = new Map<
-      string,
-      {
-        id: string;
-        pleskSubscriptionId: string;
-        status: string | null;
-        name: string | null;
-      }
+      { id: string; status: string | null }
     >(
-      subscriptionsIndexed
-        .filter((row) => row.name)
-        .map((row) => [normalizeDomainLike(String(row.name)), row]),
+      (localSubscriptions ?? [])
+        .filter((row: any) => row?.plesk_subscription_id && row?.id)
+        .map((row: any) => [
+          String(row.plesk_subscription_id),
+          {
+            id: String(row.id),
+            status: row?.status ? String(row.status) : null,
+          },
+        ]),
     );
 
-    const subscriptionNameCandidates: Array<{
-      id: string;
-      pleskSubscriptionId: string;
-      status: string | null;
-      normalizedName: string;
-    }> = subscriptionsIndexed
-      .filter((row) => row.name)
-      .map((row) => ({
-        id: row.id,
-        pleskSubscriptionId: row.pleskSubscriptionId,
-        status: row.status,
-        normalizedName: normalizeDomainLike(String(row.name)),
-      }));
-
     const domainsForUpsert = domainsRaw
       .map((item: any) => {
         const domainId = item?.id ?? item?.guid ?? item?.name;
         const domainName = item?.name ?? item?.domain_name ?? item?.domain;
-        const normalizedDomainName = domainName
-          ? normalizeDomainLike(String(domainName))
-          : null;
         const subExternalId =
           item?.subscription?.id ?? item?.subscription_id ?? item?.webspace_id;
-        const rawExternalSubscriptionId = subExternalId
+        const externalSubscriptionId = subExternalId
           ? String(subExternalId)
           : null;
-        const subscriptionNameHint =
-          item?.subscription?.name ??
-          item?.subscription_name ??
-          item?.webspace_name ??
-          item?.webspace ??
-          null;
-
-        const localSubscriptionByExternal = rawExternalSubscriptionId
-          ? subscriptionByExternalId.get(rawExternalSubscriptionId)
+        const localSubscription = externalSubscriptionId
+          ? subscriptionByExternalId.get(externalSubscriptionId)
           : undefined;
-        const localSubscriptionByLocalId = rawExternalSubscriptionId
-          ? subscriptionByLocalId.get(rawExternalSubscriptionId)
-          : undefined;
-        const localSubscriptionByName = subscriptionNameHint
-          ? subscriptionByName.get(
-              normalizeDomainLike(String(subscriptionNameHint)),
-            )
-          : undefined;
-        const localSubscriptionByDomainName = normalizedDomainName
-          ? subscriptionByName.get(normalizedDomainName)
-          : undefined;
-        const localSubscriptionBySuffix = normalizedDomainName
-          ? findBestSuffixSubscriptionMatch(
-              normalizedDomainName,
-              subscriptionNameCandidates,
-            )
-          : undefined;
-        const localSubscription =
-          localSubscriptionByExternal ??
-          localSubscriptionByLocalId ??
-          localSubscriptionByName ??
-          localSubscriptionByDomainName ??
-          localSubscriptionBySuffix;
-
-        const externalSubscriptionId = localSubscription
-          ? localSubscription.pleskSubscriptionId
-          : subscriptionNameHint
-            ? String(subscriptionNameHint)
-            : rawExternalSubscriptionId;
         const rawCreated = item?.created_at ?? item?.created;
         const sourceCreatedAt = rawCreated
           ? new Date(String(rawCreated)).toISOString()
@@ -328,10 +219,6 @@ export async function syncPleskInstance(
       })
       .filter(Boolean) as Array<Record<string, unknown>>;
 
-    const unlinkedDomains = domainsForUpsert.filter(
-      (domain) => !domain.subscription_id,
-    );
-
     if (domainsForUpsert.length > 0) {
       const { error } = await supabase
         .from("plesk_domains")
@@ -366,10 +253,6 @@ export async function syncPleskInstance(
       metadata: {
         subscriptions_seen: subscriptionsRaw.length,
         domains_seen: domainsRaw.length,
-        unlinked_domains: unlinkedDomains.length,
-        unlinked_domain_samples: unlinkedDomains
-          .slice(0, 25)
-          .map((domain) => String(domain.domain_name ?? "unknown")),
       },
     });
 
@@ -442,146 +325,3 @@ export async function syncPleskInstance(
     throw error;
   }
 }
-
-export async function backfillDomainSubscriptionLinks(
-  supabase: SupabaseLike,
-  input: {
-    agencyId: string;
-    instanceId: string;
-    actorUserId?: string | null;
-  },
-) {
-  const { agencyId, instanceId, actorUserId } = input;
-
-  const { data: subscriptions, error: subscriptionsError } = await supabase
-    .from("plesk_subscriptions")
-    .select("id, plesk_subscription_id, name, status")
-    .eq("agency_id", agencyId)
-    .eq("plesk_instance_id", instanceId);
-
-  if (subscriptionsError) {
-    throw new Error(subscriptionsError.message);
-  }
-
-  const { data: domains, error: domainsError } = await supabase
-    .from("plesk_domains")
-    .select("id, domain_name, external_subscription_id, subscription_id")
-    .eq("agency_id", agencyId)
-    .eq("plesk_instance_id", instanceId)
-    .is("subscription_id", null);
-
-  if (domainsError) {
-    throw new Error(domainsError.message);
-  }
-
-  const subscriptionByExternalId = new Map<
-    string,
-    { id: string; status: string }
-  >(
-    (subscriptions ?? [])
-      .filter((subscription: any) => subscription?.plesk_subscription_id)
-      .map((subscription: any) => [
-        String(subscription.plesk_subscription_id),
-        {
-          id: String(subscription.id),
-          status: subscription?.status
-            ? String(subscription.status)
-            : "unknown",
-        },
-      ]),
-  );
-
-  const subscriptionByName = new Map<string, { id: string; status: string }>(
-    (subscriptions ?? [])
-      .filter((subscription: any) => subscription?.name)
-      .map((subscription: any) => [
-        normalizeDomainLike(String(subscription.name)),
-        {
-          id: String(subscription.id),
-          status: subscription?.status
-            ? String(subscription.status)
-            : "unknown",
-        },
-      ]),
-  );
-
-  const subscriptionNameCandidates: Array<{
-    id: string;
-    status: string;
-    normalizedName: string;
-  }> = (subscriptions ?? [])
-    .filter((subscription: any) => subscription?.name)
-    .map((subscription: any) => ({
-      id: String(subscription.id),
-      status: subscription?.status ? String(subscription.status) : "unknown",
-      normalizedName: normalizeDomainLike(String(subscription.name)),
-    }));
-
-  let linkedCount = 0;
-  const failures: Array<{ domain_id: string; error: string }> = [];
-
-  for (const domain of domains ?? []) {
-    const matchByExternal = domain?.external_subscription_id
-      ? subscriptionByExternalId.get(String(domain.external_subscription_id))
-      : undefined;
-    const matchByDomainName = domain?.domain_name
-      ? subscriptionByName.get(normalizeDomainLike(String(domain.domain_name)))
-      : undefined;
-    const normalizedDomainName = domain?.domain_name
-      ? normalizeDomainLike(String(domain.domain_name))
-      : null;
-    const matchBySuffix = normalizedDomainName
-      ? findBestSuffixSubscriptionMatch(
-          normalizedDomainName,
-          subscriptionNameCandidates,
-        )
-      : undefined;
-    const linkedSubscription =
-      matchByExternal ?? matchByDomainName ?? matchBySuffix;
-
-    if (!linkedSubscription) continue;
-
-    const { error: updateError } = await supabase
-      .from("plesk_domains")
-      .update({
-        subscription_id: linkedSubscription.id,
-        status: linkedSubscription.status,
-      })
-      .eq("id", domain.id)
-      .eq("agency_id", agencyId);
-
-    if (updateError) {
-      failures.push({
-        domain_id: String(domain.id),
-        error: updateError.message,
-      });
-      continue;
-    }
-
-    linkedCount += 1;
-  }
-
-  await supabase.from("actions_log").insert({
-    agency_id: agencyId,
-    actor_user_id: actorUserId ?? null,
-    target_type: "plesk_instance",
-    target_id: instanceId,
-    action: "domain_subscription_backfill",
-    status: failures.length > 0 ? "failed" : "success",
-    error_message:
-      failures.length > 0
-        ? `${failures.length} domain links failed during backfill`
-        : null,
-    metadata: {
-      attempted: (domains ?? []).length,
-      linked: linkedCount,
-      failures: failures.slice(0, 25),
-    },
-  });
-
-  return {
-    attempted: (domains ?? []).length,
-    linked: linkedCount,
-    failed: failures.length,
-  };
-}