The Dashboard Frontend (React Product UI)

This is the customer-facing control panel for Doppio Box: the page where a logged-in user logs in, creates/starts/stops/resets dev boxes, tops up their wallet, pays for plans, and reads their subscription/transaction history. It is a single-page React app, not a Frappe Desk page and not a Jinja portal. The marketing landing page (/devbox) and the SPA (/dashboard) are separate things served from the same app — see §2.

Audience: a frontend dev who has never seen this codebase. Everything below is verified against the source.

1. The Stack

Note on "Radix": the task brief says Radix, but this project actually uses Base UI (@base-ui/react). shadcn components here use the Base UI render={<...>} prop pattern (e.g. DropdownMenuTrigger render={<Button .../>}) rather than Radix's asChild. yarn.lock contains zero @radix-ui packages.

Design system

components/ui/ holds ~30 shadcn primitives (button, dialog, sheet, table, badge, card, combobox, dropdown-menu, input, input-otp, tabs, sidebar, sonner, skeleton, empty, tooltip, select, textarea, label, field, separator, alert-dialog…). They are not documented individually here — they are stock shadcn wrappers. Two things worth knowing:

• Theme is dark-by-default and driven entirely by CSS variables in OKLCH (src/index.css:8-75). The primary brand color is a green (--primary: oklch(0.60 0.13 163)). Never hardcode colors — use the --color-* tokens exposed via @theme inline (src/index.css:77-117).
• Button has the usual variants plus two compact icon sizes used in this app: icon-xs (size-6, used for the row "⋯" actions trigger) and icon-sm (size-7, used for the header logout button). See components/ui/button.tsx:29-30.

How it talks to the backend

Almost every server interaction goes through frappe-react-sdk hooks, which under the hood call Frappe's REST API with the session cookie + CSRF token:

There are also three raw fetch() calls that bypass the SDK, all hitting /api/resource/Dev Box/{slug} or /api/method/run_doc_method directly and manually attaching window.csrf_token:

• Polling fallback for box status in devbox-list.tsx:175 and create-devbox-dialog.tsx:278.
• Fetching site/code URLs once a box is active (create-devbox-dialog.tsx:300).
• Setting the box title right after creation (create-devbox-dialog.tsx:483).

run_doc_method is Frappe's generic "call a whitelisted method on a document" endpoint; the dashboard uses it to invoke Dev Box controller methods (stop_box, start_box, reset_box, change_title, fetch_stats).

2. How Frappe serves the SPA

The dashboard is a www page, bootstrapped by Frappe.

build:  vite build --base=/assets/benchspace/dashboard/   →  ../benchspace/public/dashboard/
        then  copy-html-entry: cp public/dashboard/index.html → benchspace/www/dashboard.html

(dashboard/package.json:8,11, dashboard/vite.config.ts:21)

So the flow is:

1. vite build emits hashed JS/CSS into benchspace/public/dashboard/assets/ (served by Frappe at /assets/benchspace/dashboard/...).
2. The generated index.html is copied to benchspace/www/dashboard.html so Frappe serves it at the route /dashboard.
3. benchspace/www/dashboard.py:get_context() runs server-side and injects a CSRF token + a small boot dict.
4. The HTML inline-sets window.csrf_token = '{{ frappe.session.csrf_token }}' (dashboard.html:14) — this is what the raw fetch() calls read.

<!-- benchspace/www/dashboard.html -->
<div id="root"></div>
<script>
  window.csrf_token = '{{ frappe.session.csrf_token }}';
  // TODO: load boot data here (context file is created in `www` directory)
</script>

dashboard.py also exposes get_context_for_dev() (developer-mode only) so the Vite dev server (yarn dev, port 8080, proxyOptions.ts proxies /api, /app, /assets, /files, /private to the bench webserver) can fetch the same boot data while running outside Frappe.

Two routes, two HTML files

The landing page is documented only at the inventory level (see table) — it is plain Tailwind HTML with one scroll-listener script, no React.

Boot & auth sequence

FrappeProvider is given siteName={window.location.hostname} (App.tsx:50) so the SDK knows which site to call. Authentication is cookie-based: Frappe's session cookie is set on OTP verify, and useFrappeAuth reads it. There is no token storage in JS.

3. App shell & routing

Component / routing map

App.tsx — routing + auth gate

• AuthGate (App.tsx:30): while useFrappeAuth().isLoading → centered spinner. If !currentUser || currentUser === "Guest" → <LoginForm onSuccess={() => { getUserCookie(); updateCurrentUser() }} />. Otherwise → <AuthenticatedApp/>.
• AuthenticatedApp (App.tsx:10): nests all routes inside <DashboardLayout/>:
  • index / → "My Boxes" heading + <DevBoxList/>.
  • /billing → <BillingPage/>.
  • * → <Navigate to="/" replace/> (unknown paths bounce home).
• <Toaster/> (sonner) is mounted once at the root for all toasts.

DashboardLayout (components/layout/dashboard-layout.tsx)

The persistent chrome around every page:

• SidebarProvider + <AppSidebar/> + SidebarInset (the main column).
• Header (h-14, bordered): SidebarTrigger (the collapse/expand button) on the left; on the right, a wallet balance Badge (only if customer.exists) that links to /billing, the current user's email as muted text, and a Logout ghost icon-button (LogOut icon) calling useFrappeAuth().logout().
• <Outlet/> renders the active route in a scrollable area.
• A fixed floating Help button (bottom-right circular CircleHelp FAB) that is a mailto: link to developers@buildwithhussain.com (dashboard-layout.tsx:71-77).
• Subscribes to the wallet_updated socket event and re-fetches get_customer so the header balance stays live (dashboard-layout.tsx:39).

AppSidebar (components/layout/app-sidebar.tsx)

• Header label "Doppio Box".
• One group "Workspace" with exactly two nav items (app-sidebar.tsx:16-19):
  • Dev Boxes → / (icon Box)
  • Billing → /billing (icon Wallet)
• Active item is highlighted by comparing useLocation().pathname to the item URL.

Mobile behavior (hooks/use-mobile.ts + sidebar primitive)

• useIsMobile() returns true below a 768px breakpoint via matchMedia (hooks/use-mobile.ts:3).
• On mobile the sidebar primitive renders inside a Sheet (off-canvas drawer, width 18rem) toggled by openMobile state instead of the inline collapsible rail (components/ui/sidebar.tsx:182).
• Keyboard shortcut: Cmd/Ctrl + B toggles the sidebar (components/ui/sidebar.tsx:31,96-100).

4. The Dev Box experience (the "My Boxes" page)

DevBoxList (components/devbox/devbox-list.tsx) is the heart of the app. It loads the user's boxes, decorates them with trial info, renders the table, and owns every dialog and toast.

(screenshot pending: Dev Box list)

Data loading

• useFrappeGetDocList("Dev Box", …) fetches name, title, status, site_url, code_url, subscription_end_date, is_pool, ordered by modified desc, up to 100 rows (devbox-list.tsx:38).
• A second list query reads Dev Box Subscription filtered to user = currentUser, is_trial = 1, status not in [Failed] (devbox-list.tsx:57). The set of dev_box names from this query is merged onto each row as is_trial_subscription (devbox-list.tsx:67-75) — that boolean drives the "Free Trial" badge and which subscription-action button shows.
• Loading → "Loading boxes…"; error → "Failed to load boxes."; empty → an Empty state with a "Create Doppio Box" button (devbox-list.tsx:328-345).

The table columns (components/devbox/columns.tsx)

DataTable (components/devbox/data-table.tsx) is a thin TanStack-table wrapper (core row model only, no sorting/pagination/filtering). The columns:

Column 6 — the subscription-action button (columns.tsx:149-169)

Exactly one of four buttons (or nothing) renders, based on status, whether the subscription is still active (hasActiveSubscription), and whether it is a trial:

All four handlers in DevBoxList just setRenewDevbox(name), which opens CreateDevBoxDialog with renewForDevBox set (devbox-list.tsx:193-207,361-368).

Column 7 — the "⋯" actions dropdown (columns.tsx:170-256)

Trigger is a ghost icon-xs button (MoreHorizontal). Menu items are gated by status; separators are inserted between groups only when both sides exist. Full inventory:

The reset comment in code notes the backend enforces the subscription gate per role (System Managers bypass), so the frontend shows Reset whenever the status is resettable (columns.tsx:184-188).

Start / Stop — toasts + realtime + polling fallback

handleStartBox / handleStopBox (devbox-list.tsx:93-123) follow the same pattern:

1. toast.loading("Stopping {name}…"), store the toast id keyed by box slug, and add the slug to activeToastSlugs.
2. await runDocMethod({ dt:"Dev Box", dn:name, method:"stop_box" }), then mutate() to refresh the list.
3. On error: toast.error(...), drop the toast.

Progress is then reconciled by socket.io events:

• devbox_progress {slug, step} → updates the loading toast text (devbox-list.tsx:125).
• devbox_status_update {slug, status} → resolves the toast to success/error and mutate()s (devbox-list.tsx:152).

Because sockets can be missed, a 30s polling fallback runs while any toast is active: it fetches /api/resource/Dev Box/{slug} and, if status is active|stopped|error, resolves the toast (devbox-list.tsx:164-191).

Other DevBoxList dialogs/actions

• Change Name dialog (devbox-list.tsx:394-414): a Dialog with one Input (pre-filled with current title), Cancel + Save buttons, Enter-to-submit. Save → run_doc_method change_title {title} then mutate() + success toast.
• Download Workspace is a two-part flow: the menu item opens a confirm AlertDialog (devbox-list.tsx:369-382, "We'll prepare a ZIP and email you a link", Cancel / Continue). Continue → benchspace.api.devbox.download_workspace {devbox}, toast "Download queued — you'll receive an email shortly". When ready, the workspace_download_ready socket event fires a success toast with a "Download" action button that window.opens the file URL (devbox-list.tsx:269-279).

Create Doppio Box button

Top-right of the list (and inside the empty state): Create Doppio Box (Plus icon) → setShowCreateDialog(true) → opens CreateDevBoxDialog with no renewForDevBox (devbox-list.tsx:322-327).

5. CreateDevBoxDialog — the wizard (create and renew)

components/devbox/create-devbox-dialog.tsx is a multi-step stepper used for both first-time creation and renewing/extending/upgrading an existing box (when renewForDevBox is set, isRenewal = true, header switches to "Renew Doppio Box"). Steps are tracked by a Step union (create-devbox-dialog.tsx:50):

template → plan → billing → paymentMethod → review → provisioning

(screenshot pending: Create Dev Box wizard)

A StepIndicator row at the top shows progress (create-devbox-dialog.tsx:522-544). The Template step is hidden if there is only one template; the Billing step is hidden if the user already has a customer record (hasCustomer).

Data the dialog fetches (all whitelisted GETs, only while open)

Step-by-step buttons & API calls

Template (:546-583): grid of selectable cards (auto-selects the default template; auto-advances if only one). Button: Next (disabled until a template is picked) → plan.

Plan (:585-645): grid of PlanCards showing USD price (big), INR price, per-month breakdown, and a "Save X%" badge for multi-month plans (PlanCard, :1016). If trialInfo.eligible and not a renewal, a dashed free-trial box appears with an optional name Input and a Start Free Trial button → benchspace.api.billing.start_free_trial {devbox_template} → jumps straight to provisioning (:330-343). Footer: Back (only if template step exists) + Next → paymentMethod (existing customer) or billing (new customer) (:345-348).

Billing (:647-711, new customers only): Combobox Country* , Input Billing Name*, Textarea Billing Address*, Input Tax ID (optional). Back → plan, Next → paymentMethod (disabled until country+name+address filled, billingValid, :327).

Payment Method (:713-780): up to two big choice buttons —

• Wallet (only if hasCustomer): shows balance; disabled if balance < amount. Click → handlePayWithWallet → initiate_devbox_order {payment_method:"wallet", …} → goes to provisioning and refetchCustomer() (:381-407).
• Card / UPI: click → initiateRazorpayOrder → initiate_devbox_order {payment_method:"razorpay", …} → sets orderData, goes to review (:355-379).
• If wallet is short, a "Top up {amount} to use wallet" link opens the TopUpDialog (:764-772).
• Footer: Back → plan (existing customer) or billing.

Review (Razorpay only, :782-854): optional DevBox Name Input, a summary card (template/plan/duration/billing/amount), an Edit billing details link (existing customers → opens a Sheet, :921), and the big Pay {amount} button → handlePayNow:

• loads the Razorpay script (lib/razorpay.ts), opens Razorpay Checkout with key_id/order_id from the order.
• On success handler: calls handle_devbox_renewal (renewal) or handle_devbox_payment (new) with the razorpay ids + subscription_name, then sets the returned slug and goes to provisioning (:427-447).
• During review the dialog cannot be closed (canClose = step !== "review", :495, showCloseButton/guarded onOpenChange).

Provisioning (:856-910): three states —

• In progress: spinner + live provisioningStep text fed by the devbox_progress socket event (:245).
• Active: green check, "Your Doppio Box is ready!", and Open Site / Open Code external links (URLs fetched via raw fetch once status flips active, :298), plus a Done button. Reaching active also calls onCreated() which mutate()s the parent list.
• Error: red X, "Provisioning failed… payment was successful, contact support", Close button.
• Same 30s fetch polling fallback for status as the list (:273-295). If the user typed a name, it is pushed after creation via raw run_doc_method change_title (:481-492).

Edit-billing Sheet (:921-966): right-side Sheet with Billing Name / Address / Tax ID (country & currency locked). Save → benchspace.api.wallet.update_customer_billing then refetchCustomer().

Create-a-box sequence

Wallet path is the same minus Razorpay: initiate_devbox_order(payment_method=wallet) returns the slug directly and jumps to provisioning.

6. ResetDevBoxDialog (components/devbox/reset-devbox-dialog.tsx)

(screenshot pending: Reset Dev Box dialog)

A destructive type-to-confirm dialog. Body warns reset wipes files, packages, Frappe data, SSH keys, git config, editor extensions — but keeps URL, name, and subscription.

• If the box is downloadable (active/stopped), an "Optionally, download workspace first" link (Download icon) triggers the same download flow (reset-devbox-dialog.tsx:60-69, wired via onDownloadWorkspace in devbox-list.tsx:390).
• An Input where the user must type the exact box label (title || name). The Reset dev box (destructive) button is disabled until input.trim() === label; Enter also confirms (:40-46,78,87).
• Confirm → DevBoxList.confirmReset → run_doc_method reset_box with the same loading-toast + socket/poll resolution pattern as start/stop (devbox-list.tsx:223-236).
• Cancel button closes without action.

7. StatsDialog (components/devbox/stats-dialog.tsx)

(screenshot pending: Stats dialog)

Opened from "View Stats". On open it calls run_doc_method fetch_stats once (no polling — it's a one-shot fetch per open, stats-dialog.tsx:33-50). Shows a spinner, then three StatItems in a grid: CPU (Cpu icon), Memory (MemoryStick), Disk (HardDrive), each a string from {cpu_usage, memory_usage, disk_usage}. On failure: "Failed to fetch stats". No buttons besides the implicit dialog close.

8. Wallet & Billing area

BillingPage (pages/billing-page.tsx) is the /billing route.

(screenshot pending: Billing page)

• Wallet balance card (billing-page.tsx:56-73): big balance via formatCurrency, currency sub-label, and a Top up button (size="lg") → opens TopUpDialog. Re-fetches on the wallet_updated socket event.
• Tabs (:75-86): Wallet (default) → WalletTransactionsTable; Subscriptions → SubscriptionsTable.
• Hosts the shared TopUpDialog and a CreateDevBoxDialog opened in renewal mode when a subscription row's Renew is clicked (:88-105).

WalletTransactionsTable (components/wallet/wallet-transactions-table.tsx)

Calls benchspace.api.wallet.get_wallet_transactions {limit:100}. Columns: Date, Type (badge: Top-up=default, Plan Purchase=secondary, Refund/Adjustment=outline), Description, Amount (green with + when credit, :96-100), Balance (ending_balance). Empty → "No wallet transactions yet. Top up to get started." No row buttons. See page 08 for the money model.

SubscriptionsTable (components/wallet/subscriptions-table.tsx)

useFrappeGetDocList("Dev Box Subscription", …) (100 rows, newest first). A second list query resolves box titles for the linked dev_box names (subscriptions-table.tsx:85). Columns: Plan, Box (title + mono slug, or slug), Status (badge), Start, End, Method (badge Razorpay/Wallet), Amount (right-aligned formatCurrency), and a trailing Renew button shown only when the row has a dev_box and status is Active or Expired (:140,179-188) → onRenew(dev_box) → opens the renewal CreateDevBoxDialog in the parent. Empty → "You don't have any subscriptions yet."

TopUpDialog (components/wallet/top-up-dialog.tsx)

(screenshot pending: Top-up dialog)

Reused from both BillingPage and inside CreateDevBoxDialog. Two modes:

• First-time (no customer): shows Country* Combobox (locks wallet currency — India→INR, else USD), Billing Name*, Billing Address*, Tax ID (optional). Country options from get_countries.
• Returning: just the amount section, in the existing wallet currency.

Amount section: preset chip buttons (INR [500,1000,2500,5000] / USD [5,10,25,50]) plus a custom-amount number Input bounded INR 100–50000 / USD 5–1000 (top-up-dialog.tsx:56-59). Footer: Cancel + Pay {amount} (disabled until formValid).

Pay flow (:122-176): benchspace.api.wallet.initiate_topup → loadRazorpayScript() → open Razorpay → on success benchspace.api.wallet.confirm_topup {order_id, payment_id, signature} → success toast + onSuccess() (parent re-fetches balance) + close. Dialog can't be dismissed while loading.

9. Auth UI — LoginForm (components/auth/login-form.tsx)

(screenshot pending: Login - OTP step)

Two-step passwordless login (email → 6-digit OTP). Right half is a decorative gradient panel (desktop only). Backend details are in page 09.

• Email step: Input (type=email, autofocus) + Continue button (disabled while sending or empty) → benchspace.api.auth.send_otp {email} → advances to OTP step and starts a 30s resend cooldown (login-form.tsx:27-37).
• OTP step: InputOTP with 6 digit slots (digits only, REGEXP_ONLY_DIGITS), a Change email text button (back to email step), a Verify button (disabled until 6 digits) → benchspace.api.auth.verify_otp_and_login {email, otp} → on success calls onSuccess() (which the App uses to refresh the session). A Resend code link appears after the cooldown counts down (:50-58,131-145).
• Errors render as small destructive text under the form.

10. Complete UI inventory

Realtime (socket.io) events consumed

Screenshot placeholders

The orchestrator should capture real production screenshots for each placeholder below (saved under docs/doppiobox-wiki/screenshots/):

• screenshots/devbox-list.png — the "My Boxes" table with at least one box (showing status badge, Site/Code links, subscription countdown, the subscription-action button, and the ⋯ menu, ideally opened).
• screenshots/create-devbox-wizard.png — the CreateDevBoxDialog, ideally on the Plan step showing plan cards + the free-trial box and the stepper.
• screenshots/reset-devbox-dialog.png — the ResetDevBoxDialog with the type-to-confirm input and destructive button.
• screenshots/stats-dialog.png — the StatsDialog showing CPU/Memory/Disk for an active box.
• screenshots/billing-page.png — the Billing page: wallet balance card + Top up button + the Wallet/Subscriptions tabs.
• screenshots/top-up-dialog.png — the TopUpDialog showing preset amount chips + custom amount input.
• screenshots/login-email.png — LoginForm email step (email field + Continue + the right-side gradient panel on desktop).
• screenshots/login-otp.png — LoginForm OTP step (6-slot OTP input + Verify + resend countdown).