AI Dashboard engineering guide

Use this guide for changes to the AI Dashboard monorepo. Keep the frontend, shared package, standalone services, functions, and storage migrations independently testable and releasable.

Repository map

Path	Responsibility
apps/dashboard/	React 19 and Vite 7 application, routes, pages, hooks, i18n, unit tests, and Playwright checks.
packages/shared/	Shared API client, configuration, contexts, stores, hooks, providers, utilities, and UI.
services/menu-import/	Python FastAPI menu-source adapters, normalization, optional image mirroring, and Ordering.co API sync.
services/meta-ads/	Python FastAPI Meta OAuth, campaign, insights, token encryption, and persistence workflows.
supabase/functions/	Deno-based functions for the repository's selected server-side Supabase workflows.
supabase/migrations/	Versioned database schema and policy changes.
scripts/, brand/, and design/	Repository quality, formatting, localization, metadata, and Ordering.co design-system conformance tools.
turbo.json and root package.json	Workspace task graph and root commands.
wrangler.jsonc	Static application asset serving and observability configuration; it is not deployment evidence.

Frontend setup

The root declares Node.js 20 or newer and Yarn 1.22.0. Use the checked-in lockfile and run commands from the monorepo root unless a focused workspace command is shown.

yarn install --frozen-lockfile
yarn dev

To run only the browser application:

yarn workspace dashboard dev

Vite uses port 3000 by default. Confirm the rendered app is pointed at an approved non-production project before signing in or opening a route that can initialize sockets, analytics, notifications, or provider requests.

Environment configuration

Use the checked-in .env.example files as key-name inventories for the dashboard and each service. Create ignored local .env files and obtain values from the relevant environment owner. Never copy values from a deployed environment, another developer, browser storage, logs, or documentation examples.

Classify variables before use:

• VITE_* values are browser-visible and must never contain service-role keys, internal secrets, OAuth client secrets, token-encryption keys, or privileged provider credentials.
• API, billing, socket, importer, advertising, and public Supabase boundaries must all point to the intended test environment.
• Python services own their provider, database, encryption, storage, callback, and internal-auth secrets.
• Supabase functions receive trusted values through the approved function secret mechanism, not committed source or frontend configuration.

Tests and quality checks

Run the narrowest affected test first, then the applicable workspace and root gates.

yarn workspace dashboard test --run
yarn workspace dashboard test:coverage
yarn lint
yarn test
yarn format:check
yarn brand:check
yarn test:brand
yarn build

The Dashboard workspace also provides Playwright suites and focused Ordering.co surface, design, localization, metadata, and overlay checks. Use their repository scripts instead of reconstructing command flags. Live-readonly suites require separate authorization and known environment evidence; a test name alone does not make an external request safe.

For standalone services, create a local virtual environment from that service directory, install its requirements.txt, and run pytest:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pytest

Use synthetic fixtures. Keep virtual environments, generated coverage, browser results, and local secret files out of commits.

Change workflow

1. Identify the owning boundary in Services and data boundaries.
2. Trace the frontend route through its page, hook, shared API client, and server contract.
3. Use the API Reference for public request and response schemas; do not derive a contract from a hook alone.
4. Add unit tests at the owning package and service tests for every changed backend stage.
5. Cover loading, empty, denied, partial, provider-failure, retry, and success states as applicable.
6. Run the affected conformance, i18n, formatting, test, and build gates.
7. Verify a production build locally with synthetic data. Keep deployment as a separately authorized action.

Build and release boundary

yarn build runs the Turbo build graph; yarn build:cloudflare builds the Dashboard workspace for static asset serving. Wrangler configuration describes a possible serving target, but it does not prove that the current checkout, services, functions, or migrations are deployed.

Release each boundary with its own evidence:

• frontend source revision, build output, and static deployment readback;
• Ordering.co API revision and API deployment relationship;
• standalone service revision, dependency lock/evidence, health check, and provider-safe smoke test;
• function revision and secret/configuration readback; and
• database migration ledger and policy verification.

Do not combine these into a single “deployed” claim.

Troubleshooting

Symptom	Check
Turbo cannot find a task	Confirm the task exists in the target workspace package and is connected in turbo.json.
@finitless/shared cannot resolve	Run a root frozen install and confirm the workspace layout and lockfile are intact.
The browser loads but API queries are disabled or empty	Inspect sanitized endpoint feature configuration, project selection, session state, and the server response separately.
Agent provider fields are missing	Confirm the provider-schema response; do not add a client-only fallback for a server-owned schema.
Importer reports “not configured”	Confirm the browser-safe service base variable exists and the service is running; keep provider/storage secrets server-side.
Service starts but persistence fails	Verify the intended migration and policy ledger, backend database role, and encryption-key availability without printing values.
Unit tests pass but the browser flow fails	Run the focused Playwright/configuration check and inspect route, network, console, and provider boundaries separately.

Security and escalation

Escalate API authorization and core schema questions to the API owner; agent/channel contracts to their service owner; credentials, callbacks, and delivery failures to the provider owner; migrations and policies to the data owner; and deployments to the release owner. Stop when testing could create external campaigns, send messages, import customer data, change billing, write a production database, or expose a secret without an explicit effect, cleanup, and readback plan.

Related: Agents, channels, and provider integrations · Services and data boundaries