SvelteKit + PostgreSQL + WorkOS + TypeORM Enterprise Blueprint - CLAUDE.md Template

Overview

This CLAUDE.md template page is designed for developers building enterprise applications with SvelteKit, PostgreSQL, WorkOS, and TypeORM Enterprise. It provides a copyable CLAUDE.md block that you can paste into Claude Code to bootstrap a production-ready blueprint and a stack-focused guide for implementation.

When to Use This CLAUDE.md Template

• You need a production-ready CLAUDE.md template for a SvelteKit + PostgreSQL + WorkOS + TypeORM Enterprise stack.
• You want a repeatable blueprint that enforces architecture, security, and deployment rules.
• You require a ready-to-paste instruction block plus a stack-specific project structure.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: You are Claude Code, an AI coding assistant specialized in delivering enterprise-grade blueprints for SvelteKit + PostgreSQL + WorkOS + TypeORM Enterprise.

Architecture Rules:
- Use a layered architecture: API (src/routes), service layer (src/services), data layer (src/entities), and persistence (src/db/migrations).
- Use TypeORM for PostgreSQL with a robust connection pool and transaction boundaries.
- Integrate WorkOS for authentication, SSO, and directory access.
- Do not mix client-side data fetches with server-side operations; keep SSR-safe patterns.

File Structure Rules:
- src/
  - routes/
  - lib/
  - db/
  - entities/
  - migrations/
  - services/
  - repositories/
  - config/
  - workos/
  - tests/
- config/.env.example for environment defaults.

Authentication Rules:
- Use WorkOS for SSO; store session identifiers in HttpOnly cookies; validate sessions on protected endpoints.
- Enforce role-based access control (RBAC) at the service layer.
- Never trust client-side tokens for authorization decisions.

Database Rules:
- PostgreSQL with TypeORM entities; migrations tracked in src/migrations.
- Use separate databases per environment; never share credentials across environments.
- Enforce referential integrity and proper indexing for query-heavy paths.

Validation Rules:
- Use zod for runtime input validation in API handlers.
- Fail closed on missing/invalid inputs with clear error messages.

Security Rules:
- Enforce CSRF protection for state-changing endpoints.
- Use TLS, secure cookies, and proper CORS configuration for trusted origins.
- Never log secrets or plaintext credentials.

Testing Rules:
- Unit tests for services and validators; integration tests for repositories and database interactions.
- End-to-end tests for authentication flows using Playwright or Cypress.

Deployment Rules:
- Local: Docker Compose; Staging/Prod: Kubernetes or serverless where supported.
- Run migrations as part of the deployment pipeline; verify migration success before promoting to prod.

Things Claude Must Not Do:
- Do not use Prisma, Mongoose, or Drizzle in this blueprint.
- Do not bypass WorkOS by mocking authentication tokens.
- Do not commit secrets or migrate data in code.
- Do not generate client-side code that leaks internal DB schemas.

Recommended Project Structure

src/
  routes/
  lib/
  db/
  entities/
  migrations/
  services/
  repositories/
  config/
  workos/
  tests/

Core Engineering Principles

• Explicit interfaces and typed contracts across layers.
• Single source of truth for business rules.
• Testable components with clear boundaries.
• Defensive programming and explicit error handling.
• 12-factor compliant configuration and secrets management.

Code Construction Rules

• Entities defined with TypeORM decorators; use migrations for schema changes.
• Repositories abstract data access; services orchestrate business logic.
• Validation with zod; return structured error payloads.
• Environment-driven configuration; no hard-coded values.
• Do not couple WorkOS keys with client code; fetch from server only.

Security and Production Rules

• Use HttpOnly secure cookies for sessions; enable CSRF protection.
• Enforce TLS in all environments; restrict CORS to trusted origins.
• Enable logging with redact for sensitive fields; rotate secrets regularly.
• Automate migrations; verify DB health during startup.

Testing Checklist

• Unit tests for services and validators; integration tests for repositories/migrations.
• End-to-end tests for authentication and protected routes.
• Migration sanity checks on CI/CD pipelines.

Common Mistakes to Avoid

• Using client-side sources to drive authorization decisions.
• Skipping migrations or mixing environments.
• Overexposing database schemas in API payloads.
• Ignoring WorkOS token validation or misconfiguring SSO.

FAQ

What is included in this CLAUDE.md Template?

A copyable CLAUDE.md template block plus stack-specific guidelines for SvelteKit + PostgreSQL + WorkOS + TypeORM Enterprise.

Which stack does this template cover?

SvelteKit frontend, PostgreSQL database, WorkOS authentication, and TypeORM Enterprise as the ORM.

How do I integrate WorkOS into SvelteKit?

Install the WorkOS SDK, configure environment keys, and enforce SSO/session validation on protected routes.

How are migrations handled?

Use TypeORM migrations; run on deploy/startup; ensure migrations are applied before breaking changes.

Where should secrets live?

In environment variables or a secret manager; never commit secrets to code.