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, SQLite/libSQL for local development, Cloudflare D1 for production, and Cloudflare Workers.

Development

Install dependencies:

pnpm install

Create a local .env file:

DATABASE_URL=file:local.db
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:

DATABASE_URL=file:local.db pnpm db:migrate

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   # Apply Drizzle migrations to DATABASE_URL
pnpm db:studio    # Open Drizzle Studio
pnpm gen          # Regenerate Cloudflare Worker types

Environment Variables And Bindings

Required:

• DATABASE_URL: SQLite/libSQL connection URL for local development. Use file:local.db.
• 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.

Production also requires the Cloudflare D1 binding named DB, configured in wrangler.jsonc. Do not set DATABASE_URL in production unless you intentionally want to use a hosted libSQL database instead of D1.

Database

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

Runtime database selection is:

• If DATABASE_URL is set, Clearity uses the libSQL driver.
• If DATABASE_URL is not set and the Cloudflare DB binding exists, Clearity uses Drizzle's Cloudflare D1 driver.

The fastest local database is a SQLite file:

DATABASE_URL=file:local.db pnpm db:migrate

For schema changes:

pnpm db:generate
DATABASE_URL=file:local.db pnpm db:migrate

To test against Wrangler's local D1 simulator instead, leave DATABASE_URL unset, apply migrations locally, and run the app through the Cloudflare Worker build:

pnpm build
pnpm wrangler d1 migrations apply clearity-production --local
pnpm wrangler dev

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

Production uses the DB binding by default. DATABASE_URL is only needed as a production secret if you intentionally deploy against a hosted libSQL database instead of D1.

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.