CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Rhema Wave Technologies User Portal — a SvelteKit web app managing proclamations (audio content tied to solfeggio frequencies), user accounts, license keys, and authentication.

Tech Stack

Framework: SvelteKit 2.x with Svelte 5 (runes API: $props(), $state(), $derived(), $effect())
Language: TypeScript (strict mode)
Styling: Tailwind CSS 4.x (Vite plugin, not PostCSS)
Database: PostgreSQL via Prisma 7.x (driver adapter with pg pool)
Auth: better-auth with email/password + Google OAuth
Rich Text: TipTap 3.x
Runtime: Node.js 22, deployed via @sveltejs/adapter-node

Common Commands

npm run dev          # Start dev server
npm run build        # Production build
npm run check        # Type-check (svelte-kit sync + svelte-check)
npm run lint         # Prettier check + ESLint
npm run format       # Auto-format with Prettier
npm run test         # Run all tests once (vitest --run)
npm run test:unit    # Run tests in watch mode (vitest)
npx vitest run src/path/to/file.spec.ts   # Run a single test file
npm run migrate -- --name <name>          # Create a new Prisma migration
npm run deploy                            # Apply pending Prisma migrations

Architecture

Routing & Auth Guard

src/routes/(protected)/ — route group requiring authentication. The +layout.server.ts in this group checks locals.user against the DB and throws 403 if missing.
src/routes/account/setup/ — intentionally outside (protected) so logged-in users without a profile can complete setup.
src/hooks.server.ts — runs auth.api.getSession() on every request, injecting session and user into event.locals.

Server/Client Split

Auth config: src/lib/auth.ts (server) / src/lib/auth-client.ts (client)
DB access: src/lib/db.ts (server-only) — creates a pg pool with optional SSL via DO_CA_CERTIFICATE env var for DigitalOcean managed DB.
Prisma generated client outputs to src/lib/generated/prisma/ (gitignored).

Key Patterns

Svelte 5 runes throughout — use $props(), $state(), $derived(), $effect() (not Svelte 4 reactivity).
SvelteKit form actions for mutations (create/edit proclamations, registration, account setup).
API routes at src/routes/api/v1/ (proclamations, license keys).

Database Schema

Core models: User, Profile (1:1 with User), Address (belongs to Profile), Session, Account (OAuth), UserRole, Proclamation, SolfeggioFrequency, ProclamationCategory, LicenseKey. Schema lives in prisma/schema.prisma.

Testing

Vitest 4.x with two project configurations in vite.config.ts:

client — browser tests (Playwright/Chromium) matching *.svelte.{test,spec}.{js,ts}
server — Node environment tests matching *.{test,spec}.{js,ts} (excludes .svelte.*)

Global config: expect: { requireAssertions: true }.

Code Style

Prettier: tabs, single quotes, no trailing commas, semicolons, 100 char width
ESLint: flat config with typescript-eslint + eslint-plugin-svelte
Svelte files parsed with prettier-plugin-svelte; class sorting via prettier-plugin-tailwindcss

Deployment

Server infrastructure: NixOS, configured declaratively in the Webserver-Infra repo
Secrets: Managed via sops-nix (no plaintext .env files on the server)
CI/CD: Forgejo Actions on push to main → npm ci → migrate → build → rsync to /var/lib/portal/current/ → restart
Hosting: DigitalOcean droplet (NixOS), managed PostgreSQL with SSL, self-hosted Forgejo runner
Portal path: /var/lib/portal/current (deployed by CI, owned by portal user)
Reverse proxy: Caddy with automatic HTTPS at rhemawavetech.com
Logs: journalctl -u portal -f

Environment Variables

Required: DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET. Optional: DO_CA_CERTIFICATE (path to CA cert for managed DB SSL).

4.1 KiB Raw Blame History