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/dashboard/page.tsx

@@ -17,10 +17,6 @@ type ActionLogSummary = Pick<
   "target_id" | "status" | "action" | "created_at" | "error_message"
 >;
 
-function normalizeDomainLike(value: string) {
-  return value.trim().toLowerCase().replace(/\.$/, "");
-}
-
 export default async function DashboardPage() {
   const context = await getServerAgencyContextOrRedirect();
   const supabase = createSupabaseServerClient() as any;
@@ -54,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 })
@@ -105,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;
@@ -118,51 +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 autoSyncByInstance = new Map<
     string,
     { status: string; created_at: string; error_message: string | null }
@@ -217,28 +167,7 @@ export default async function DashboardPage() {
       <DashboardControls
         instances={instances ?? []}
         subscriptions={subscriptions ?? []}
-        domains={(domains ?? []).map((domain) => {
+        domains={domains ?? []}
-          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 joinedStatus =
-            joinedStatusByLocalId ??
-            joinedStatusByExternalId ??
-            joinedStatusByName;
-
-          return {
-            ...domain,
-            status: joinedStatus ?? "unknown",
-          };
-        })}
         autoSyncByInstance={Object.fromEntries(autoSyncByInstance.entries())}
       />
     </main>

lib/plesk/sync.ts

@@ -22,19 +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(/\.$/, "");
-}
-
 export async function syncPleskInstance(
   supabase: SupabaseLike,
   instance: InstanceRow,
@@ -167,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);
 
@@ -175,95 +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; status: string | null }
-        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;
-      }
     >(
-      subscriptionsIndexed
+      (localSubscriptions ?? [])
-        .filter((row) => row.name)
+        .filter((row: any) => row?.plesk_subscription_id && row?.id)
-        .map((row) => [normalizeDomainLike(String(row.name)), row]),
+        .map((row: any) => [
+          String(row.plesk_subscription_id),
+          {
+            id: String(row.id),
+            status: row?.status ? String(row.status) : null,
+          },
+        ]),
     );
 
     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 =
+        const localSubscription = externalSubscriptionId
-          item?.subscription?.name ??
+          ? subscriptionByExternalId.get(externalSubscriptionId)
-          item?.subscription_name ??
-          item?.webspace_name ??
-          item?.webspace ??
-          null;
-
-        const localSubscriptionByExternal = rawExternalSubscriptionId
-          ? subscriptionByExternalId.get(rawExternalSubscriptionId)
           : 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 localSubscription =
-          localSubscriptionByExternal ??
-          localSubscriptionByLocalId ??
-          localSubscriptionByName ??
-          localSubscriptionByDomainName;
-
-        const externalSubscriptionId = localSubscription
-          ? localSubscription.pleskSubscriptionId
-          : subscriptionNameHint
-            ? String(subscriptionNameHint)
-            : rawExternalSubscriptionId;
         const rawCreated = item?.created_at ?? item?.created;
         const sourceCreatedAt = rawCreated
           ? new Date(String(rawCreated)).toISOString()
@@ -292,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")
@@ -330,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")),
       },
     });
 
@@ -406,124 +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",
-        },
-      ]),
-  );
-
-  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 linkedSubscription = matchByExternal ?? matchByDomainName;
-
-    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,
-  };
-}