Dashboard engineering guide

Use this guide for source changes to the Ordering.co Dashboard repository. Keep development configuration isolated from customer and production environments, and verify API effects separately from rendered UI.

Architecture and repository map

Path	Responsibility
src/App.js	Authenticated application shell, route registration, client route gates, and top-level lifecycle behavior.
src/pages/	Page-level adapters that compose operator workflows.
src/@/components-dashboard/	In-tree shared components, SDK code, contexts, UI primitives, and controllers consumed through Vite aliases.
src/config.json and src/config.js	Base client configuration and the merge with an optional runtime window.__CONFIG__ override.
src/__tests__/ and colocated __tests__/	Vitest and Testing Library coverage for routes, pages, contexts, utilities, and UI behavior.
i18n/	Translation catalog generation, validation, and synchronization tools.
vite.config.js	React build, aliases, test configuration, coverage scope, and dist/config.json output.
wrangler.toml, worker/, and docs/CLOUDFLARE.md	Cloudflare build and serving configuration; repository presence is not deployment proof.

The app uses React 18, React Router 5, styled-components, and a Vite 7 toolchain. Shared Ordering.co contexts coordinate API, session, configuration, orders, businesses, language, realtime, and other cross-page state.

Local setup

Prerequisites are Node.js 22 or newer and pnpm 9.15.0 through Corepack.

corepack enable
corepack prepare pnpm@9.15.0 --activate
pnpm install --frozen-lockfile
pnpm dev

The development script starts Vite on port 3001. Docker is also described by the repository, but use a local fixture or explicitly approved non-production environment either way.

Configure the environment safely

The repository provides .env.example; copy only its key names into a local ignored .env, then obtain values from the environment owner. Do not copy .env, src/config.json, browser storage, or runtime configuration between environments.

Remember:

• every value exposed to Vite or bundled client configuration is readable in the browser;
• project, API, socket, language, and application identity must describe the same environment;
• runtime overrides merge nested api and socket objects with the base configuration;
• analytics, notifications, support, sockets, and authenticated bootstrap may initialize during normal app startup, so loading the application is not a guaranteed read-only test; and
• use synthetic accounts and records for development. Never place customer data or credentials in fixtures, screenshots, logs, or committed configuration.

Development and validation commands

pnpm dev
pnpm lint:check
pnpm test
pnpm test:coverage
pnpm i18n:check-generated
pnpm i18n:verify
pnpm build
pnpm preview

Use pnpm test:watch during focused work. The production build allocates a larger Node heap because of the bundle size. Run the narrowest relevant test first, then the lint, test, i18n, and build checks required by the change. Do not use pnpm lint as a read-only check because that script applies fixes.

Change workflow

1. Trace the route from src/App.js into its page and in-tree component/controller.
2. Identify the API, configuration, session, realtime, plugin, or provider context the workflow uses.
3. Confirm the published API contract instead of inferring a server schema from client calls.
4. Add or update tests beside the owning page, component, context, or utility.
5. Verify loading, empty, denied, error, success, and read-only states that the change can reach.
6. Run a production build and inspect the affected route with synthetic data.
7. Verify that the intended revision was deployed using your organization's release system; a successful local build or workflow run alone does not confirm deployment.

Build and release boundary

pnpm build creates static assets in dist/. The repository also includes Wrangler commands for local Worker development and environment-specific deployment. Run a deployment command only with explicit authorization, the intended Cloudflare account/environment, approved secrets, and a rollback/readback plan.

After an authorized release, record the source revision, deployment identifier, target environment, build result, and live readback separately. Do not infer any of these from branch names.

Troubleshooting

Symptom	Check
Vite cannot resolve ~components or ~ui	Confirm the complete in-tree src/@/components-dashboard checkout and Vite aliases.
Startup shows the wrong project or backend	Stop before authenticating; inspect sanitized base and runtime configuration and clear only known local test state.
A protected route redirects unexpectedly	Inspect session initialization, the route's client level gate, and read-only flags; then confirm server authorization separately.
API reads work but realtime updates do not	Check the socket boundary, authenticated connection state, and provider/network errors independently.
Tests pass locally but CI fails	Match the pinned pnpm version, frozen lockfile install, Node version accepted by CI, and the exact non-mutating lint/i18n commands.
Build exits for memory pressure	Ensure the documented heap allocation is applied and the host has sufficient memory; do not weaken tests or minification to conceal the failure.

Security and escalation

Escalate to the API owner for authorization or contract ambiguity, the project/configuration owner for environment selection, the provider owner for credentials and callbacks, and the release owner for deployment. Stop testing when a workflow could write customer data, trigger provider activity, send a notification, alter billing, or expose credentials without an approved effect and cleanup plan.

Related: Dashboard integrations, API, and provider handoffs