This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
pnpm dev- Start development server with preheat scriptpnpm build- Build production application (vite build)pnpm check- Run TypeScript type checkingpnpm lint- Run prettier + eslint + stylelintpnpm test- Run Playwright testspnpm test:unit- Run Vitest unit tests
pnpm db:studio- Open Prisma Studio GUIpnpm db:generate- Generate Prisma clientpnpm db:push- Push schema changes to databasepnpm db:seed- Seed database with test datapnpm i-changed-the-schema- Shortcut for push + generate after schema changes
pnpm test:ui- Run Playwright tests with UIpnpm check:watch- Run TypeScript check in watch mode
- Frontend: SvelteKit 3 with Svelte 5, TypeScript 6, Vite 8
- Backend: Node.js (22.17+) with SvelteKit server-side rendering
- Database: MySQL with Prisma ORM (PlanetScale)
- Caching: Redis (Upstash)
- Deployment: Vercel with Node.js 22.x runtime
- Monitoring: Sentry for error tracking
src/
├── routes/
│ ├── (site)/ # Main website layout
│ ├── (blank)/ # Clean layout for embeds
│ └── api/ # API endpoints
├── lib/ # Reusable components
├── server/ # Server-side logic and utilities (server-only)
├── state/ # Svelte stores for client state
├── styles/ # CSS architecture with themes
├── actions/ # Svelte actions
├── utilities/ # Shared utilities (safe on client and server)
├── env.ts # Declares every environment variable the app reads
└── params.ts # Route param matchers
SvelteKit 3 treats any server directory as server-only, so code that client components import (e.g. src/utilities/transcripts.ts) must live outside src/server/.
Paths use package.json subpath imports (SvelteKit's config.alias is deprecated): #lib/*, #server/*, #state/*, #utilities/*, #actions/*, #assets/*, #styles/*, plus #const and #hooks.server.
- Subpath imports map literally, so include the file extension. Use
.jsfor.tsfiles:import { prisma_client } from '#server/prisma-client.js',import Icon from '#lib/Icon.svelte'. #means a fragment in CSS, so CSSurl()s use relative paths:url('../assets/Grit Mask@2x.png').
Every variable must be declared in src/env.ts with defineEnvVars. Undeclared variables aren't available. Import them from $app/env/private (server) or $app/env/public (PUBLIC_ vars). Mark build-time values with static: true; runtime ones use a schema.
The application manages podcast content with these key models:
- Show: Episodes with metadata, transcripts, AI-generated content
- User: GitHub OAuth authentication with role-based access
- Guest: Guest profiles with social links and appearances
- Transcript: Full transcription with utterances and speaker identification
- Video: YouTube integration with playlists
- UserSubmission: User-generated content submissions
- Show notes are stored as markdown files in the
/shows/directory - AI-generated content (summaries, tweets, show notes) using Claude Sonnet 5.5 through OpenRouter in
src/server/ai/notes.ts - Automated transcription via Deepgram
- Multi-layer caching with Redis for performance
- Components: PascalCase for
.sveltefiles (e.g.,ShowCard.svelte) - Variables/Functions: snake_case for variables, functions, and props
- Constants: UPPER_CASE for true constants only
- Types: PascalCase for TypeScript interfaces
- Use
$statefor reactive state declarations - Use
$derivedfor computed values - Use
$effectfor side effects and lifecycle - Use
$propsfor component props with destructuring - Use
$bindablefor two-way bindable props - Use classes for complex state management (state machines)
- CSS variables defined in
src/styles/variables.css - Use
bgandfgconvention for background/foreground colors - Custom media queries for responsive design:
@custom-media --below-med (width < 700px); @custom-media --above-med (width > 700px);
- Components: Group related components in
/src/lib/ - Routes: Use SvelteKit's file-based routing with layout groups
- State: Svelte stores in
/src/state/for global state - Server: All server-side logic in
/src/server/
- Audio player built on media-chrome, which also controls the YouTube player for episodes with video
- Media Session API integration
- Position saving and resume functionality
- Offline episodes saved with the Cache API, player state in IndexedDB
- Client-side search using FlexSearch, in a web worker so it doesn't block the page
- Prefix search over episode titles and show notes (
/content.json)
- Role-based access control
- Content management for shows and guests
- AI content generation tools
- Transcript management
- Redis caching for database queries
- IndexedDB for offline data storage
- CDN caching via
cache-controlheaders on show pages and APIs
- Create components in
/src/lib/for reusable UI - Add routes in
/src/routes/following the layout structure - Use Prisma for database operations via
/src/server/prisma-client.ts - Implement caching for database queries using the cache utilities
- Add proper TypeScript types and error handling
- Modify
/prisma/schema.prisma - Run
pnpm i-changed-the-schemato apply changes - Update seed data if needed in
/prisma/seed.ts
- Use Playwright for integration tests
- Use Vitest for unit tests
- Run linting before commits
- Test across different screen sizes and devices
- Application deploys to Vercel automatically
- Environment variables managed through Vercel dashboard
- Database hosted on PlanetScale
- Redis cache on Upstash
Existing global state (player, youtube_player, etc.) uses Svelte stores in src/state/*.ts. For new complex state, use a class in a .svelte.ts file:
// src/state/counter.svelte.ts
class Counter {
count = $state(0);
increment() {
this.count += 1;
}
}
export const counter = new Counter();import { prisma_client } from '#server/prisma-client.js';
import { super_cache_mang } from '#server/cache/cache_mang.js';
// Wrap queries in super_cache_mang to cache them in Redis
const shows = await super_cache_mang('tasty_shows', () =>
prisma_client.show.findMany({
where: { show_type: 'TASTY' },
orderBy: { number: 'desc' }
})
);<script lang="ts">
import type { Show } from '@prisma/client';
import { player } from '#state/player.js';
let { show }: { show: Show } = $props();
let is_current = $derived($player.current_show?.number === show.number);
</script>
<div class="show-card">
<h3>{show.title}</h3>
<button onclick={() => player.start_show(show)}>
{is_current ? 'Playing' : 'Play'}
</button>
</div>Remember to follow the existing code conventions and patterns when adding new features or modifying existing code.