From d696557641025f9555247d05e4bffc31ea8b73e4 Mon Sep 17 00:00:00 2001
From: Daniel Kirby <dkirby24.10@gmail.com>
Date: Fri, 5 Jun 2026 23:26:04 +0100
Subject: [PATCH] docs: document clearity setup and deployment

---
 README.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b9b5900
--- /dev/null
+++ b/README.md
@@ -0,0 +1,166 @@
+# 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, and Cloudflare Workers.
+
+## Development
+
+Install dependencies:
+
+```sh
+pnpm install
+```
+
+Create a local `.env` file:
+
+```sh
+DATABASE_URL=file:local.db
+ORIGIN=http://localhost:5173
+BETTER_AUTH_SECRET=replace-with-a-long-random-secret
+```
+
+Generate a Better Auth secret with:
+
+```sh
+openssl rand -base64 32
+```
+
+Apply database migrations:
+
+```sh
+DATABASE_URL=file:local.db pnpm db:migrate
+```
+
+Create an initial admin user:
+
+```sh
+ADMIN_EMAIL=admin@example.com \
+ADMIN_PASSWORD='change-me' \
+ADMIN_NAME='Administrator' \
+DATABASE_URL=file:local.db \
+pnpm admin:create
+```
+
+Start the development server:
+
+```sh
+pnpm dev
+```
+
+Useful development commands:
+
+```sh
+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
+
+Required:
+
+- `DATABASE_URL`: SQLite/libSQL connection URL. Use `file:local.db` for local development.
+- `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.
+
+Admin bootstrap script:
+
+- `ADMIN_EMAIL`: Email address for the admin account.
+- `ADMIN_PASSWORD`: Password for the admin account.
+- `ADMIN_NAME`: Optional display name. Defaults to `Administrator`.
+- `ADMIN_OVERWRITE`: Set to `1` to update an existing admin user.
+
+## Database
+
+The application schema lives in `src/lib/server/db`. Drizzle migration files live in `drizzle`.
+
+Local development currently uses the libSQL client through `DATABASE_URL`, so the fastest local database is a SQLite file:
+
+```sh
+DATABASE_URL=file:local.db pnpm db:migrate
+```
+
+For schema changes:
+
+```sh
+pnpm db:generate
+DATABASE_URL=file:local.db pnpm db:migrate
+```
+
+## Production Deployment
+
+The Worker is configured in `wrangler.jsonc` and built with the SvelteKit Cloudflare adapter.
+
+Authenticate Wrangler:
+
+```sh
+pnpm wrangler login
+pnpm wrangler whoami
+```
+
+Create a production D1 database:
+
+```sh
+pnpm wrangler d1 create clearity-production
+```
+
+Wrangler prints a `database_id`. Add it to `wrangler.jsonc`:
+
+```jsonc
+{
+	"d1_databases": [
+		{
+			"binding": "DB",
+			"database_name": "clearity-production",
+			"database_id": "<database_id>"
+		}
+	]
+}
+```
+
+Regenerate Worker types after changing Wrangler bindings:
+
+```sh
+pnpm gen
+```
+
+Apply SQL migrations to the remote D1 database:
+
+```sh
+for file in drizzle/*.sql; do
+	pnpm wrangler d1 execute clearity-production --remote --file "$file"
+done
+```
+
+Set production secrets:
+
+```sh
+pnpm wrangler secret put ORIGIN
+pnpm wrangler secret put BETTER_AUTH_SECRET
+```
+
+This codebase currently reads the database through `DATABASE_URL`. If production is deployed against Cloudflare D1, wire the runtime database client to the `DB` D1 binding before deploying. If production is deployed against a hosted libSQL database instead, set `DATABASE_URL` as a Worker secret:
+
+```sh
+pnpm wrangler secret put DATABASE_URL
+```
+
+Build and deploy:
+
+```sh
+pnpm build
+pnpm wrangler deploy
+```
+
+Preview the built Worker locally:
+
+```sh
+pnpm preview
+```
+
+Create the first production admin user by running the admin script against the production database connection before exposing the app to users.