Skip to content

Developer Onboarding

This page is your starting point for working on Workbench AI as a developer. It assumes you’re comfortable with TypeScript/React and basic CLI tools.

Prerequisites

Install the following before you start:

  • Node.js: v18+ (recommended)
    • Check: node -v
  • npm: v9+
    • Check: npm -v
  • Git: for cloning and branching.
  • Supabase CLI (for local DB & migrations, optional but recommended):
    • Install: https://supabase.com/docs/guides/cli
  • Stripe test account & keys (for end-to-end subscription/billing tests):
    • Dashboard: https://dashboard.stripe.com/test
    • You’ll need:
    • STRIPE_SECRET_KEY
    • STRIPE_WEBHOOK_SECRET (per webhook endpoint)
    • Test product/price IDs (for subscription plans)

You do not need production keys or secrets for local dev.

Cloning the repo

Use the GitHub SSH alias configured for this workspace:

cd /home/yearnmister/dev
git clone git@github.com-codex:anthenkes/workbench-ai.git workbench-ai-docs
cd workbench-ai-docs

Create and check out your own feature branch off main for any work:

git checkout main
git pull origin main
git checkout -b my-feature-branch

For the docs project specifically, we use a docs-architecture branch as an example; follow the same pattern for your own tasks.

Installing dependencies

From the repo root:

npm install

This installs all dependencies for the Vite SPA, docs tools, and any shared tooling.

Common scripts (from package.json):

  • npm run dev – run the Vite app locally.
  • npm run build – production build for the Vite app.
  • npm run lint – linting.
  • npm run test – tests (if configured).

Environment configuration

Workbench AI relies on several environment variables. For local development, you’ll typically have:

  • A frontend env file for Vite.
  • A Supabase env/CLI config for the database.
  • Edge function env vars configured in your Supabase project.

1. Frontend (Vite)

Create a .env.local file in the project root (not committed to git):

# Supabase (frontend)
VITE_SUPABASE_URL="https://YOUR_PROJECT_ID.supabase.co"
VITE_SUPABASE_ANON_KEY="YOUR_SUPABASE_ANON_KEY"

# Optional: analytics, error monitoring, etc.
# VITE_SENTRY_DSN="YOUR_SENTRY_DSN"

These values should come from your Supabase project settings (project URL + anon key), using a development project.

2. Supabase CLI

The repository already includes supabase/config.toml, which points the CLI at the correct project configuration.

If you’re running Supabase locally:

supabase start
# or
supabase db reset   # to reset DB and apply migrations

If you’re using a hosted Supabase project for dev:

  • Ensure supabase/config.toml matches your project’s project_id and API URL.
  • Use supabase db push to apply migrations to that project when needed.

3. Edge functions (server-side env vars)

Edge functions under supabase/functions/ rely on server-side environment variables configured in the Supabase project dashboard.

Common ones (placeholders only):

SUPABASE_URL="https://YOUR_PROJECT_ID.supabase.co"
SUPABASE_SERVICE_ROLE_KEY="YOUR_SUPABASE_SERVICE_ROLE_KEY"

STRIPE_SECRET_KEY="YOUR_STRIPE_SECRET_KEY"
STRIPE_WEBHOOK_SECRET="YOUR_STRIPE_WEBHOOK_SECRET"
STRIPE_STARTER_PRICE_ID="price_XXXX_STARTER"
STRIPE_PROFESSIONAL_PRICE_ID="price_XXXX_PROFESSIONAL"

OPENAI_API_KEY="YOUR_IMAGE_API_KEY"  # for nameplate generation
CRON_SECRET="YOUR_INTERNAL_CRON_SECRET"  # for scheduled sync functions

Configure these via Supabase → Project Settings → Functions → Environment Variables. Do not commit real values.

For a full list, see Environment Variables.

Running the app locally

1. Start Supabase (optional local DB)

If you want a fully local stack:

supabase start

This launches a local Postgres instance with Supabase APIs and storage. After that, apply migrations:

supabase db reset   # drops & recreates DB, applies migrations
# or
supabase db push    # applies pending migrations

If you’re using a hosted dev project, skip supabase start and rely on the remote DB; just ensure migrations have been applied (see below).

2. Apply migrations

Migrations live under supabase/migrations/ and define all tables, RLS, and helper functions.

To apply migrations to your target project:

# For local project managed by Supabase CLI
supabase db reset

# Or for remote dev project
supabase db push

Make sure your Supabase CLI is authenticated and pointing at the correct project (see supabase/config.toml).

3. Run the Vite app

From the repo root:

npm run dev

This starts the Vite dev server (default http://localhost:5173 unless configured otherwise).

Log in via the UI using a Supabase Auth user that exists in your dev project. You may need to:

  • Manually create a user via Supabase Auth or the app’s signup flow.
  • Ensure user_profiles and companies rows exist via the signup/migration logic.

Working with docs (MkDocs)

The documentation you’re reading is served from docs-site/ using MkDocs Material.

To run the docs locally:

  1. Install MkDocs and Material (if not already):
pip install mkdocs mkdocs-material mkdocs-mermaid2-plugin
  1. From docs-site/:
cd docs-site
mkdocs serve
  1. Open the URL printed by MkDocs (usually http://127.0.0.1:8000).

Any changes under docs-site/docs/ will hot-reload in the docs site.

Testing & linting

Linting

Run lint checks:

npm run lint

Fix issues as reported. If you introduce new lint rules or tooling, add a short note to a future dev/conventions.md.

Tests

If tests are configured (check package.json):

npm test
# or
npm run test

Keep tests fast and focused. When adding new features, add tests for:

  • Hooks that encapsulate non-trivial logic (e.g., pricing, plan limits).
  • Utility functions (src/lib/**, src/utils/**).

Typical “first change” checklist

When onboarding a new dev, a good first task is to make a small, end-to-end change:

  1. Clone the repo and create a feature branch.
  2. Configure env vars for Supabase/Stripe (test-only).
  3. Run migrations against a dev Supabase project.
  4. Start the app via npm run dev.
  5. Make a UI tweak (e.g., text in a non-critical component), plus a small docs change.
  6. Run lint/tests.
  7. Commit & push, open a PR.

Once you’re comfortable with the structure, move on to deeper architecture, flows, and API/data changes documented in other sections.

For more detail on structure and conventions, see: