clearity/README.md

Clearity

Clearity is a workspace, client, and contract management platform for managed office operations. It tracks clients, contacts, addresses, rooms, services, bookings, contracts, invoices, and workspace admins from a SvelteKit dashboard.

The app is built with SvelteKit, Svelte 5, shadcn-svelte, Superforms, Better Auth, Drizzle ORM, Cloudflare D1, and Cloudflare Workers.

Development

Install dependencies:

pnpm install

Create a local .env file:

ORIGIN=http://localhost:5173
BETTER_AUTH_SECRET=replace-with-a-long-random-secret

Generate a Better Auth secret with:

openssl rand -base64 32

Apply database migrations:

pnpm db:migrate:local

Start the development server:

pnpm dev

Open http://localhost:5173/login. If no Better Auth users exist yet, Clearity shows a first-admin setup form instead of the normal sign-in form. Submitting it creates the initial user with the default Better Auth admin role and signs you in.

Useful development commands:

pnpm check        # Wrangler types, SvelteKit sync, and svelte-check
pnpm lint         # Prettier check and ESLint
pnpm format       # Format the codebase
pnpm db:generate  # Generate Drizzle migrations after schema changes
pnpm db:migrate:local  # Apply migrations to the local D1 database
pnpm db:migrate:remote # Apply migrations to the remote D1 database
pnpm gen          # Regenerate Cloudflare Worker types

Environment Variables And Bindings

Required:

• ORIGIN: Public app origin, for example http://localhost:5173 locally or https://clearity.example.com in production.
• BETTER_AUTH_SECRET: Secret used by Better Auth.
• Cloudflare D1 binding DB, configured in wrangler.jsonc.

Local development uses the same DB binding shape as production. SvelteKit's Cloudflare adapter populates platform.env.DB from wrangler.jsonc during dev and preview, and Wrangler stores local D1 data in its local state directory.

Database

The application schema lives in src/lib/server/db. Drizzle migration files live in drizzle.

Clearity always uses Drizzle's Cloudflare D1 driver through the DB binding. Apply migrations to the local D1 database before starting the app:

pnpm db:migrate:local

For schema changes:

pnpm db:generate
pnpm db:migrate:local

Production Deployment

The Worker is configured in wrangler.jsonc and built with the SvelteKit Cloudflare adapter.

Authenticate Wrangler:

pnpm wrangler login
pnpm wrangler whoami

Create a production D1 database:

pnpm wrangler d1 create clearity-production --binding DB

Wrangler prints a database_id. Replace the placeholder in wrangler.jsonc:

{
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "clearity-production",
			"database_id": "<database_id>",
			"migrations_dir": "drizzle"
		}
	]
}

Regenerate Worker types after changing Wrangler bindings:

pnpm gen

Apply SQL migrations to the remote D1 database:

pnpm wrangler d1 migrations apply clearity-production --remote

Set production secrets:

pnpm wrangler secret put ORIGIN
pnpm wrangler secret put BETTER_AUTH_SECRET

Build and deploy:

pnpm build
pnpm wrangler deploy

Create the first production admin by opening /login after migrations have run. The setup form is only shown while the Better Auth user table is empty.