compassmock/docs/development/getting-started.md

Getting Started

This guide walks you through setting up Compass for local development. By the end you'll have the dev server running, a local D1 database with migrations applied, and a clear picture of every environment variable the app needs.

Prerequisites

You need these installed before anything else:

• Bun (v1.1+) - the package manager and runtime. Compass uses Bun exclusively; don't mix in npm or pnpm.
• Wrangler CLI (v4+) - Cloudflare's CLI for D1 databases, secrets management, and deployment. Installed as a dev dependency, but having it globally helps for ad-hoc commands.
• Node.js (v20+) - needed by Next.js and some tooling even though Bun handles package management.

For mobile development (optional):

• Xcode (macOS only) - for iOS builds via Capacitor
• Android Studio - for Android builds via Capacitor

Clone and install

git clone git@github.com:High-Performance-Structures/compass.git
cd compass
bun install

That's it. Bun resolves everything from bun.lockb.

Environment variables

Copy .env.example to .dev.vars for local development:

cp .env.example .dev.vars

Wrangler reads .dev.vars automatically when running the local dev server. For production, set these as Cloudflare secrets via wrangler secret put <KEY>.

Required

Variable	Description
WORKOS_API_KEY	API key from your WorkOS dashboard. Powers all authentication.
WORKOS_CLIENT_ID	Client ID from WorkOS. Paired with the API key.
WORKOS_COOKIE_PASSWORD	At least 32 characters. Encrypts the session cookie. Generate with openssl rand -base64 24.
NEXT_PUBLIC_WORKOS_REDIRECT_URI	OAuth callback URL. Use http://localhost:3000/callback locally.

AI agent

Variable	Description
OPENROUTER_API_KEY	API key from OpenRouter. The AI agent routes through OpenRouter to access the kimi-k2.5 model. Without this, the chat agent won't function.

NetSuite integration (optional)

Only needed if connecting to NetSuite for financial sync.

Variable	Description
NETSUITE_ACCOUNT_ID	Your NetSuite account identifier.
NETSUITE_CLIENT_ID	OAuth 2.0 client ID from NetSuite.
NETSUITE_CLIENT_SECRET	OAuth 2.0 client secret.
NETSUITE_REDIRECT_URI	OAuth callback. Use http://localhost:3000/api/netsuite/callback locally.
NETSUITE_TOKEN_ENCRYPTION_KEY	AES-GCM encryption key for storing tokens at rest. Generate with openssl rand -hex 32.
NETSUITE_CONCURRENCY_LIMIT	Max concurrent API requests. Defaults to 15 (NetSuite's shared limit).

Google Drive integration (optional)

Variable	Description
GOOGLE_SERVICE_ACCOUNT_ENCRYPTION_KEY	Encrypts stored service account credentials. Generate with openssl rand -hex 32.

Push notifications (optional, mobile)

Variable	Description
FCM_SERVER_KEY	Firebase Cloud Messaging server key for sending push notifications to iOS/Android.

GitHub deployment (optional)

Variable	Description
GITHUB_TOKEN	GitHub repo token for automatic deployments.
GITHUB_REPO	Repository in owner/repo format. Default: High-Performance-Structures/compass.

Production-only

The wrangler.jsonc config sets WORKOS_REDIRECT_URI as a Worker var pointing to the production domain. You don't need this locally since NEXT_PUBLIC_WORKOS_REDIRECT_URI covers it.

Development commands

Core

Command	What it does
bun dev	Starts the Next.js dev server with Turbopack on port 3000.
bun run build	Production build via Next.js.
bun preview	Builds then runs on the Cloudflare Workers runtime locally. Good for catching runtime differences between Node and Workers.
bun lint	Runs ESLint across the codebase.
bun deploy	Builds with OpenNext and deploys to Cloudflare Workers.

Database

Compass uses Cloudflare D1 (SQLite) with Drizzle ORM. The schema is split across multiple files and Drizzle generates migrations from them.

Command	What it does
bun run db:generate	Generates migration SQL from schema changes. Run this after modifying any src/db/schema*.ts file.
bun run db:migrate:local	Applies pending migrations to your local D1 instance.
bun run db:migrate:prod	Applies pending migrations to the production D1 database.

The schema files that Drizzle watches (configured in drizzle.config.ts):

src/db/schema.ts           - core tables (users, projects, customers, vendors, etc.)
src/db/schema-netsuite.ts  - netsuite sync tables
src/db/schema-plugins.ts   - plugin/skills tables
src/db/schema-agent.ts     - agent conversation tables
src/db/schema-ai-config.ts - AI usage tracking and model preferences
src/db/schema-theme.ts     - custom themes and user preferences
src/db/schema-google.ts    - google drive auth and starred files
src/db/schema-dashboards.ts - custom AI-built dashboards

Migrations live in drizzle/ and are applied in order. Never modify an existing migration file - always generate a new one.

Mobile (Capacitor)

The mobile app is a webview wrapper that loads the live Cloudflare deployment. It's not a static export.

Command	What it does
bun cap:sync	Syncs web assets and Capacitor plugins to native projects. Run after adding new Capacitor plugins.
bun cap:ios	Opens the Xcode project for iOS development.
bun cap:android	Opens the Android Studio project.

Other

Command	What it does
bun run cf-typegen	Regenerates the cloudflare-env.d.ts type definitions from wrangler.jsonc bindings. Run after changing Worker bindings.

Running locally

1. Make sure .dev.vars has at least the WorkOS variables set.
2. Apply database migrations:

   bun run db:migrate:local
   

3. Start the dev server:

   bun dev
   

4. Open http://localhost:3000.

The Turbopack dev server is fast. Hot reload works for both server and client components.

To test against the actual Cloudflare Workers runtime (catches D1 quirks, binding issues, etc.):

bun preview

This builds with OpenNext, then runs a local Workers emulator. It's slower to start but more representative of production behavior.

Deploying

Compass deploys to Cloudflare Workers via OpenNext:

bun deploy

This runs opennextjs-cloudflare build followed by opennextjs-cloudflare deploy. The Worker is configured in wrangler.jsonc with:

• D1 database binding (DB)
• Assets binding for static files
• Cloudflare Images binding
• AI binding
• Self-reference service binding (for internal routing)
• Custom domain route (compass.openrangeconstruction.ltd)

Production secrets are set via wrangler secret put <KEY> and managed in the Cloudflare dashboard.

Project structure overview

src/
  app/           - Next.js App Router pages, API routes, server actions
  components/    - React components (ui/ for shadcn primitives)
  db/            - Drizzle schema files and getDb() helper
  hooks/         - Custom React hooks (including native/mobile hooks)
  lib/           - Business logic, integrations, utilities
  types/         - Global TypeScript type definitions

drizzle/         - Generated migration SQL files
ios/             - Xcode project (Capacitor)
android/         - Android Studio project (Capacitor)
docs/            - Documentation
public/          - Static assets

For a deeper dive into the architecture, see the docs/architecture/ directory.