---
title: "AI Dashboard engineering guide"
description: "Set up, test, build, and troubleshoot the Ordering.co AI Dashboard monorepo safely."
canonical: https://docs.ordering.co/docs/developers/ai-dashboard/engineering-guide/
---

# 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.

```bash
yarn install --frozen-lockfile
yarn dev
```

To run only the browser application:

```bash
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.

```bash
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`:

```bash
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](https://docs.ordering.co/docs/developers/ai-dashboard/services-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](https://docs.ordering.co/docs/developers/ai-dashboard/agents-channels-provider-integrations/) · [Services and data boundaries](https://docs.ordering.co/docs/developers/ai-dashboard/services-data-boundaries/)