create-dashboard

You are helping the user build a custom dashboard from the Gooseworks dashboard template. The app must run on port 3847 from a single Express process that serves both the API routes and the built React UI so it appears in the Gooseworks App tab.

Where the source lives (read this first)

The runnable project folder is /home/user/dashboard. That is the ONLY directory you should cd into for any npm / build / server command. Most files inside it are symlinks pointing back into the canonical source under the agent's workspace folder (the file you'd see at the canonical path is the same file you'd see through the symlink — it's one file, two paths). The runnable project folder also holds two real local directories that must NOT be on the workspace mount: node_modules (dependencies) and dist (built bundle).

/home/user/dashboard/                    ← cd here for everything
  package.json, package-lock.json,
  server.js, src/, vite.config.ts, …    (symlinks → workspace canonical source)
  node_modules/, dist/, .vite/, .cache/  (real local dirs — never on workspace)

What this means for you:

• Always cd /home/user/dashboard before running npm / vite / node / any shell command. Tools resolve modules from the node_modules next to the cwd. Running them from the canonical source path under the workspace folder will install node_modules directly into the workspace mount — that puts tens of thousands of files on s3fs, hits its filesystem-semantics limits (npm gets ENOTEMPTY on package renames), and the install will spin forever.
• Edits to source files at /home/user/dashboard/src/... (or any other symlinked path) auto-persist to the workspace mount through the symlink. There is no separate sync step. You may also edit the canonical path directly; both paths land in the same file.
• Never run npm install, npm ci, vite build, or node server.js from inside the workspace canonical source folder. Those commands will pollute the workspace with node_modules / dist / build caches and break future restores.

Non-negotiable constraints

1. Always use the template workflow (React + Vite + Tailwind + Express). Do not rebuild this in another framework.
2. The runnable project folder is /home/user/dashboard. Use that literal path when telling the user where you cd or which file you edited; do not invent shell-variable strings.
3. Always cd /home/user/dashboard before running npm / vite / node. Edits to symlinked source files inside it propagate to persistent storage automatically; no separate sync step is needed.
4. node_modules and dist are LOCAL only. Never copy them into the workspace folder.
5. Use one runtime port (3847) and one server process. No separate frontend dev server.

State handling

Before editing, inspect:

• whether the runnable project folder's package.json is a symlink (it should be — this confirms the symlink layout is in place)
• whether the local node_modules folder inside the runnable project folder is populated
• whether port 3847 has a healthy server

Then follow this decision flow:

• All three OK: move to customization.
• Symlinks missing or node_modules empty: ask the platform to re-run the start flow (it will set up symlinks + npm install + build + launch).
• package.json is a real file (not a symlink): the sandbox is in a legacy state — ask the platform to re-run install/start so the symlink layout gets put in place.

The platform's start/install orchestrator handles symlink setup, dependency install, build, and launch automatically. You don't run those steps by hand unless something is broken.

Discovery and planning

Before coding:

1. Clarify what the user wants to visualize if unclear.
2. Always check the agent's database first. If the agent has a Turso database with relevant tables, the dashboard must read from it. Never invent placeholder rows, mock arrays, or hard-coded sample data when real data is available. Use mock data only when the user explicitly asks for a demo with no DB, and clearly label it as mock in the UI.
3. Inspect the database schema using the database query tool:
   • list tables
   • inspect columns for relevant tables
   • run a small sample query to confirm shape and row counts before wiring a chart
   • if the relevant tables are missing, follow the Empty-database handling section below — propose a schema and create the tables rather than defaulting to mock data
4. If the request is vague, confirm a one-sentence implementation plan.

Data source preference

Order of preference for every panel, chart, and table:

1. Live query against the agent's database via the runQuery helper or a read-only API route.
2. A user-provided file (CSV, JSON) already in the workspace.
3. Mock data — only as a last resort, with explicit user permission, and labelled as such on screen.

Empty-database handling (important)

The user is often non-technical and will not know how to create a schema themselves. Do not fall back to "sample data" the moment a table is missing. Instead, when the DB is reachable but the tables needed for the requested dashboard do not exist:

1. Confirm which tables exist by listing them through the database tool.
2. Tell the user in plain language that the table(s) the dashboard needs are not there yet, and propose a small, sensible schema based on what they asked for (e.g., for a "revenue dashboard": a deals table with id, name, amount, stage, closed_at, plus a revenue_daily rollup if useful). Keep the schema minimal — only the columns the requested charts actually need.
3. Get a one-line confirmation from the user, then create the tables via the database tool. Use sensible types and primary keys. Add helpful indexes for the columns the dashboard will filter or group by.
4. Offer to seed a small set of realistic example rows so the charts have something to render immediately. Seed only if the user agrees, and tell them clearly that these rows are starter examples they can delete or replace.
5. Wire the dashboard to the newly created tables. Do not also keep a mock-data fallback in the code — once the table exists, the empty state in the UI is enough.

If the user declines schema creation, render a calm empty state ("no data yet — connect a table named X with columns A, B, C to see this chart") in stone tones rather than filling the chart with fake numbers.

Never create or alter tables that already contain user data without an explicit instruction. Never drop tables. All table creation must be additive.

Implementation guidance

Template structure to use:

• A server entry module for API routes and static serving.
• The root App component for route registration.
• A layouts folder under src/components/layouts/ that holds six shell components — pick the one that matches what the user is building (see "Choosing a layout" below).
• A pages folder for page implementations.
• A small API helper module exporting a runQuery function for data access from pages.

For each new page:

1. Add a page component to the pages folder.
2. Pull data using the runQuery helper, or a dedicated read-only API route when SQL becomes complex.
3. Add route wiring in the root App component.
4. Add a navigation entry in whichever layout shell the App component is wrapped in (sidebar nav, top nav, or tab bar — depending on the chosen layout).

Keep all dashboard endpoints read-only.

Choosing a layout

Six layout shells live in src/components/layouts/. The default App.tsx wraps routes in SidebarLayout. Swap the import + wrapper in App.tsx to the shell that matches what the user is asking for: