Before you start
Plan a live portal before building screens
For a planning-only request, describe the workflows, data contracts, storage needs, permissions, and unresolved requirements. Do not create resources, change grants, publish, or execute actions. Mark source IDs and fields as unknown until discovered; a plausible schema is not evidence of the customer’s schema.
Use existing connectors, datasets, and operation outputs for connected records. Introduce managed database storage only for explicitly requested app-owned records, and use Data Flows for reusable transformations. Build requested workflows on these capabilities using agreed business rules; do not infer additional functionality or business policy from an app label.
For each user journey, specify the source, record identities, matching rules, date window, required permissions, and whether it reads data or changes it. For requested writes, establish the destination, affected records, and allowed operation. If the write destination or behavior is unclear, continue independent read-only work and ask for the missing scope before implementing the write.
Keep browser components, shared controls, data-loading hooks, action contracts, and deployment scripts separate. Use one shared implementation for date selectors, filters, tooltips, tables, dialogs, and loading/error states. Put credentials only in the authoring environment; never in browser environment variables, bundles, fixtures, logs, or committed snapshots.
Confirm the installed SDK version and the target API environment before building around a feature. Repository source or unreleased types do not prove that a live endpoint supports a field. If a request rejects an unknown field, compare the public contract and changelog for that environment; do not bypass validation with internal routes or silently change the agreed data-access architecture.
Use the platform’s built-in app assistant. Do not add an AI backend or a second chat overlay to make app data available to it; source grants and viewer permissions supply that access. The assistant does not inherit customer facts or shared Skills and cannot see unsaved frontend state. Encode essential app calculations in governed outputs or tested action contracts; frontend prompts cannot supply runtime authorization.
Load the visible view first
- 1Define the default view before writing queries: fields, filters, calendar window, and the completeness needed for each total.
- 2Give each independent panel its own loading/error state. Start its bounded read without waiting for unrelated panels; use provider-aware concurrency limits.
- 3Render each panel as soon as its required result is complete. Fetch evidence, older history, and off-screen detail only when needed.
- 4On a horizon change, select the control immediately and show a local loader at a stable height. Keep cached ranges and unrelated controls available.
- 5Deduplicate identical in-flight reads, ignore superseded responses, and measure cold load, repeat navigation, history expansion, and refresh before release.
A successful data request is not a complete loading strategy. Design the default view around the smallest useful date window and field set. Do not download all historical transactions just because a chart offers 6M, 12M, and Max. Load the default window first; fetch older history or record-level evidence only when requested. Use calendar-month boundaries for monthly charts, and distinguish the current incomplete month from completed months.
Start independent reads concurrently with bounded concurrency that respects provider limits. Cursor-dependent pages remain sequential. Avoid awaiting every panel, every file, and every optional detail before rendering the first useful result. Independent panels need independent loading and error states; a slow history request should not hold up a recently billed clients card.
Deduplicate in-flight reads and reuse completed results in memory for the signed-in session. Key cached data by app/action revision, query inputs, workspace and user context where applicable. Define freshness and explicit refresh behavior; clear caches on identity changes. A refresh or filter change must prevent older responses from overwriting newer results. Do not persist sensitive datasets in browser storage by default.
Measure a cold initial visit, repeat navigation, a history-range change, and refresh separately. Record request count, page count, action duration, payload size, and time to the first useful panel without logging customer rows. Set a product latency target and test with representative data volume. If a view takes twenty seconds, identify whether it is waiting on sequential calls, unnecessary history, repeated metadata reads, or excess payload before increasing timeouts or concurrency. The SDK does not automatically cache action results or optimize the reads in your handler.
Keep navigation and loading states responsive
When a user selects a chart horizon or filter, update the selected control immediately and show a loading state in that region. Reserve the final chart height so loading and tooltips do not move the page. Keep unrelated controls usable, including switching back to cached data. On failure, show a retry state; never label old or partial data as the newly selected range.
Use actual URL routes for main screens and meaningful filter state where users need Back, Forward, refresh, or deep links. spa: true provides hosting fallback; it does not implement browser navigation for you. Use a router or explicit history/popstate handling, and retain the overview route when opening a detail dialog from the overview.
Use a shared accessible dialog primitive with focus management, Escape/close behavior, and viewport-centered positioning. Preserve the underlying context for confirmations rather than replacing a detail screen with a delete-only screen. Avoid nested dialogs for routine selection flows. Keep typography, button spacing, sticky table headers, empty states, and tooltips consistent across screens.
Clickable cards should open the exact promised filtered view. Explain chart units and color scales, distinguish no data from zero, and expose hover details on keyboard focus too. Reserve image dimensions and provide skeletons until brand assets load. Validate at narrow and wide viewport sizes, with slow requests, errors, empty results, and browser Back/Forward, before publishing.