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 affirmations (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 affirmations, registration, account setup).
Reusable forms — AffirmationForm.svelte is shared between create and edit via an action prop.
API routes at src/routes/api/v1/ (affirmations, license keys).

Database Schema

Core models: User, Profile (1:1 with User), Address (belongs to Profile), Session, Account (OAuth), UserRole, Affirmation, SolfeggioFrequency, AffirmationCategory, 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

Containerized via Dockerfile (multi-stage, Node 22 Alpine)
CI/CD: GitHub Actions on push to main → Podman build → deploy with --network=host
Hosted on DigitalOcean (managed PostgreSQL with SSL, self-hosted runner)
Production .env mounted from /mnt/volume_nyc3_01/Portal/.env

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).

3.9 KiB Raw Blame History