Iblai Vibe Application

/iblai-vibe-application

Add the platform application gate (admissions) — the surface a platform uses to make membership application-only: staff author application forms and review submissions, applicants fill the form on a public link and track their outcome.

It ships as two independent halves:

The two connect through a copyable link: an admin copies a form's applicant link from the Applications tab and shares it; the link opens the wizard for that form.

Common setup (brand, conventions, env files, verification): see docs/skill-setup.md.

Prerequisites

• Auth must be set up first (/iblai-vibe-auth)
• MCP server + skills configured (@iblai/mcp in .mcp.json)
• @iblai/iblai-js recent enough to export both surfaces. Verify:

  grep -rl "ApplyWizard" node_modules/@iblai/iblai-js/dist/web-containers | head -1
  

  Nothing printed → upgrade (/iblai-vibe-ops-upgrade).
• The admin half needs a reviewer account on the platform. The manage endpoints are RBAC-gated — see /iblai-vibe-rbac.
• The platform must be in application mode for the wizard to render a form. open / invite_only platforms render an informational notice instead (the gate mode, set platform-side, not from this UI).

Step 1: Check Environment

Before proceeding, check for an iblai.env in the project root. Look for PLATFORM, DOMAIN, and TOKEN variables. If the file does not exist or is missing these variables, tell the user: "You need an iblai.env with your platform configuration. Download the template and fill in your values: curl -o iblai.env https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/iblai.env"

Step 2: Mount the Admin Applications Tab

The Applications tab lives inside the Admin component, which the Account component renders under its Management tab. If the app already has an account page (/iblai-vibe-account), the tab is one prop away — pass authURL so the copyable applicant links resolve:

// app/(app)/account/page.tsx — existing Account page
<Account
  tenant={tenantKey}
  tenants={tenants}
  username={username}
  isAdmin={isAdmin}
  authURL={config.authUrl()}   // ← required for the copyable applicant link
  => {}}
  => router.push("/")}
  targetTab="management"       // opens straight on Management
/>

To give applications their own page instead, mount Admin directly:

// app/(app)/applications/page.tsx
"use client";

import { Admin } from "@iblai/iblai-js/web-containers";
import config from "@/lib/iblai/config";
import { resolveAppTenant } from "@/lib/iblai/tenant";

export default function ApplicationsAdminPage() {
  const tenantKey = resolveAppTenant();

  return (
    <div className="mx-auto w-full flex-1 overflow-auto px-4 py-8 md:w-[85vw] md:px-0">
      <Admin
        tenant={tenantKey}
        authSpaUrl={config.authUrl()}
        => {}}
      />
    </div>
  );
}

Admin renders the Applications tab unconditionally — every other tab (Users, Groups, Roles, Policies, Teams, Alerts) is behind a has*TabPermission prop, so with none of them passed the page shows Applications only. The tab reads platformKey from tenant and fetches everything itself; no other props are required.

Step 3: Add the Public Applicant Routes

The wizard is what a form's copied link opens. Create two routes so both the default-form link and per-form links work:

app/applications/[platformKey]/page.tsx            → the platform's DEFAULT form
app/applications/[platformKey]/[formId]/page.tsx   → one specific form

Both render the same component:

// app/applications/[platformKey]/page.tsx        (and .../[formId]/page.tsx)
"use client";

import ApplicationPage from "@/components/applications/application-page";

export const dynamic = "force-dynamic";

export default ApplicationPage;

// components/applications/application-page.tsx
"use client";

import { useEffect, useRef, useState } from "react";
import { useParams, useRouter } from "next/navigation";
import { ApplyWizard } from "@iblai/iblai-js/web-containers";
import { useGetAppTokensMutation } from "@iblai/iblai-js/data-layer";
import config from "@/lib/iblai/config";

/** Origin to send the applicant back to after submitting (?redirect-to=). */
function redirectTo(): string | null {
  if (typeof window === "undefined") return null;
  return new URLSearchParams(window.location.search).get("redirect-to");
}

export default function ApplicationPage() {
  const router = useRouter();
  const { platformKey, formId } = useParams<{
    platformKey: string;
    formId?: string;
  }>();
  const [getAppTokens] = useGetAppTokensMutation();
  const [dmToken, setDmToken] = useState<string | null>(null);
  const requested = useRef(false);

  // The gate calls run with the MAIN tenant's DM token — applicants are
  // usually not members of the platform they are applying to. Held in memory
  // only, so the selected tenant's stored token is left untouched.
  useEffect(() => {
    if (requested.current) return;
    requested.current = true;
    (async () => {
      const body = new FormData();
      body.append("platform_key", config.mainTenantKey() || "main");
      const { data } = await getAppTokens(body).unwrap();
      setDmToken(data?.dm_token?.token ?? null);
    })();
  }, [getAppTokens]);

  if (!platformKey || !dmToken) return <div className="p-8">Loading…</div>;

  return (
    <ApplyWizard
      platformKey={platformKey}
      {...(formId ? { formId } : {})}
      token={dmToken}
      dmUrl={config.dmUrl()}
      => router.push(redirectTo() || "/")}
    />
  );
}

Provider requirements for the applicant routes

• The wizard needs the data-layer store + initializeDataLayer only.

• Do not wrap these routes in TenantProvider — it blocks on organization membership, and applicants are usually not members. In a vibe-starter app the provider chain lives in providers/iblai-providers.tsx; skip the organization layer on these routes the same way it already skips SSO routes:

  const isApplyRoute = pathname?.startsWith("/applications") ?? false;
  // …
  <TenantProvider skip={isSsoRoute || isApplyRoute} /* … */>
  

  Leave AuthProvider in place — applicants must still be authenticated. It sends unauthenticated visitors through SSO with the current path and query preserved, so the link's ?redirect-to= survives the round trip.

• Import the SDK stylesheet once: @iblai/iblai-js/web-containers/styles.

• Keep the routes at app/applications/…, outside the (app) group, so the navbar/chrome layout does not wrap the applicant experience.

The applicant link

The Applications tab copies links in this shape — build them the same way if the app needs to render one itself (the SDK's internal helper is not exported):

<AUTH_URL>/applications/<platform-key>/<form-id>?redirect-to=<origin>
<AUTH_URL>/applications/<platform-key>?redirect-to=<origin>        # default form

AUTH_URL comes from the authSpaUrl / authURL prop, else window.__ENV__.NEXT_PUBLIC_AUTH_URL, else process.env.NEXT_PUBLIC_AUTH_URL. With none of them resolvable the copy button hides itself. Hosting the routes in this app instead of the auth SPA? Pass that origin as authSpaUrl.

Surfaces

Admin (inside the Applications tab)

Applicant (the wizard)

Form schema contract

A form is sections → fields, saved as the record's schema. The backend re-validates on save and on submit and stays authoritative.

{
  "title": "Fall Admission",
  "description": "Apply for the fall term.",
  "sections": [
    {
      "key": "students",
      "title": "Students",
      "repeatable": true,      // applicant may add several entries
      "candidate": true,       // ← entries become per-student candidates (max one such section)
      "item_label": "student", // "Add another student"
      "min_items": 1,
      "fields": [
        { "key": "name", "type": "text", "label": "Full name", "required": true },
        { "key": "grade", "type": "select", "label": "Grade",
          "options": [{ "value": "k", "label": "Kindergarten" }],
          "ui": { "widget": "radio" } },
        { "key": "transcript", "type": "file", "label": "Transcript",
          "file_config": { "allowed_extensions": ["pdf"], "max_size_mb": 5, "max_files": 2 } },
        { "key": "consent", "type": "boolean", "label": "I agree", "must_be_true": true },
        { "key": "sibling", "type": "text", "label": "Sibling name",
          "visible_if": { "field": "has_sibling", "operator": "equals", "value": true } }
      ]
    }
  ],
  "resources": [{ "label": "Handbook", "url": "https://…" }]
}

• Field types: text, textarea, email, phone, number, date, boolean, select, multi_select, file, signature, info (info displays content and collects nothing).
• Validators: min_length, max_length, pattern, min, max, min_items, max_items — each { check, value, error? }.
• visible_if operators: equals, not_equals, in, gte, lte. The field is "section.field" (absolute) or a bare "field" (same repeatable entry).
• Uploads are capped at 5 MB client-side; a field's file_config.max_size_mb may tighten that, never widen it.
• sensitive on a section or field masks the answer in the reviewer workspace (the detail payload lists masked paths in sensitive_masked).
• The question dialog edits label, type, required, placeholder, help text, options, must_be_true, and info content — it preserves visible_if, validators, and file_config untouched, so author those in the schema and they survive edits. A field's key is slugified from its label on creation and never changes afterward.

Statuses and transitions

Reviewer actions (transitionApplication, family-wide or with a candidate_id): start_review, request_info, require_interview, waitlist, accept, decline. decline with block: true adds the applicant to the ban list. message reaches the applicant (shown on the status page); note is internal.

draft and needs_more_info are the editable statuses — the applicant resumes the wizard; everything else routes to the status page.

<ApplyWizard> Props

Import from @iblai/iblai-js/web-containers (framework-agnostic bundle).

<Admin> Props (applications-relevant subset)

Import from @iblai/iblai-js/web-containers.

Data-layer hooks

From @iblai/iblai-js/data-layer — all under /api/catalog/applications/platform/… on the DM service. Every applicant-facing hook takes an optional token.

Applicant: useGetApplicationStatusQuery (the gate state that drives routing), useGetApplicationFormQuery, useCreateApplicationDraftMutation, useUpdateApplicationMutation (replaces the whole responses object, not a delta), useSubmitApplicationMutation, useUploadApplicationAttachmentMutation, useDeleteApplicationAttachmentMutation, useListOwnApplicationsQuery, useRenewApplicationMutation, useWithdrawApplicationMutation.

Forms management: useGetApplicationFormsQuery, useGetApplicationFormDetailQuery, useCreateApplicationFormMutation, useUpdateApplicationFormMutation.

Reviewer: useGetApplicationsPipelineQuery, useGetApplicationsPipelineStatsQuery, useGetApplicationAdminDetailQuery, useTransitionApplicationMutation, useCreateApplicationWaiverMutation, useDeleteApplicationWaiverMutation, useSubmitApplicationOverrideMutation, useGetApplicationNotesQuery + create/update/delete, useLazyGetApplicationAttachmentFileQuery, useGetApplicationBlocksQuery, useDeleteApplicationBlockMutation, useGetApplicationPlacementsQuery + create/update, useGetApplicationCourseAssignmentsQuery + create/delete, useInviteApplicationCandidateMutation, useLinkApplicationCandidateMutation.

Build custom application UI on these hooks rather than calling the endpoints directly — they carry the cache tags (platform_applications, platform_application_forms) the SDK components invalidate.

Step 4: Use MCP Tools for Customization

get_component_info("ApplyWizard")
get_component_info("Admin")
get_component_info("Account")
get_api_query_info("useGetApplicationStatusQuery")

Step 5: Verify

Run /iblai-vibe-ops-test before telling the user the work is ready:

1. pnpm build — must pass with zero errors
2. pnpm test — vitest must pass
3. Start dev server and touch test both halves:

   pnpm dev &
   npx playwright screenshot http://localhost:3000/account /tmp/applications-admin.png
   npx playwright screenshot http://localhost:3000/applications/<platform-key> /tmp/apply.png
   

End-to-end check: create a form in the editor, enable it, mark it default, copy its link, open it in a private window as a non-member account, submit, then decide it from the pipeline.

Important Notes

• Redux store: must include mentorReducer and mentorMiddleware; the platform API slice ships inside those bundles.
• initializeDataLayer(): 5 args (v1.2+).
• @reduxjs/toolkit: deduplicated via webpack aliases in next.config.ts.
• Peer dep: sonner — the admin surfaces toast on save/decide.
• Token nuance: the wizard's token is held in memory and never written to storage, so the selected organization's dm_token stays intact. Skip it and the wizard uses the current organization's stored token — correct only when the applicant is already a member of that organization.
• Application rules are per form. A family may hold applications on two forms of one platform; a submission on a sibling form does not block a fresh apply on this one.
• No default form set and several forms active → a bare /applications/<key> link 404s. Either mark one form default or hand out per-form links.
• Blocking checklist: a reviewer can waive individual required items (excused items stop blocking) or force-submit a stuck draft with submitApplicationOverride, which waives every missing required item.
• Placements and course assignments only apply to accepted candidates.
• The fee panel is deliberately not implemented in the reviewer workspace — fee state comes back on the gate payload but no UI drives it.
• Brand guidelines: BRAND.md