CLAUDE.md Template for SvelteKit + Neo4j + Lucia Auth + Neo4j-OGM Graph Stack

Overview

Direct answer: This CLAUDE.md template provides a copyable Claude Code blueprint for building a SvelteKit frontend backed by a Neo4j graph database, with Lucia Auth and Neo4j-OGM style patterns. It targets developers building graph-powered apps with role-based access control and strong data validation.

The template covers architecture, file structure, authentication, database rules, validation, security, testing, deployment, and anti-patterns for this stack.

When to Use This CLAUDE.md Template

• You are building a SvelteKit SPA or SSR app that stores user and domain data in Neo4j.
• You need robust authentication with Lucía Auth integrated with your routes and services.
• You want to apply Neo4j-OGM style domain modeling in a Node/TS environment.
• You require a copyable CLAUDE.md template to hand to Claude Code for generation of boilerplate code, tests, and deployment artifacts.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: You are Claude Code, a precise AI coder tasked with generating a complete, copyable CLAUDE.md file for a SvelteKit + Neo4j + Lucia Auth + Neo4j-OGM Graph Stack.

Architecture Rules: Use a clean, layered architecture with a SvelteKit frontend, a Node.js service layer, and a Neo4j database. Model domain objects with Neo4j-OGM-inspired patterns and expose a small, well-typed API layer. All queries must be parameterized to prevent injection. Authenticate using Lucia Auth and store sessions in secure cookies. Avoid any vendor-specific shortcuts that would hamper maintainability or security.

File Structure Rules: Place framework-specific code under src/, separate concerns by domain under src/lib/{domain,db,auth,graph}, and keep tests under tests/. Do not create circular dependencies between frontend and backend code.

Authentication Rules: Integrate Lucia Auth with a Node adapter and SvelteKit endpoints. Persist sessions using secure, HttpOnly cookies. Do not expose sensitive tokens in client code. Use refresh tokens only if your threat model requires them and implement rotation.

Database Rules: Use Neo4j with the official neo4j-driver. Enforce constraints for unique user emails and usernames. Use parameterized Cypher for all reads and writes. Do not perform destructive migrations in production without explicit confirmation.

Validation Rules: Validate all inputs on both client and server. Sanitize user inputs, normalize emails, and enforce strict schema on domain entities. Return consistent error shapes.

Security Rules: Never log secrets. Disable verbose server error messages to clients. Use HTTPS in production. Limit request sizes and enforce CSRF protection for mutating endpoints. Use role-based access control for sensitive operations.

Testing Rules: Implement unit tests for graph domain models, integration tests for the auth and data layer, and end-to-end tests covering login and protected routes. Use Vitest or Jest for unit/integration tests and Playwright or Cypress for end-to-end tests.

Deployment Rules: Deploy to a Node-compatible hosting with TLS termination. Use environment variables for secrets. Include a simple health check endpoint. Keep the CLAUDE.md file as the single source of truth for this blueprint. 

Things Claude Must Not Do: Do not assume Prisma, Mongoose, Drizzle, or other ORM abstractions that are not applicable to Neo4j-OGM. Do not bypass Lucia or implement custom auth that weakens security. Do not generate code that leaks secrets in logs or bundles. Do not omit required dependencies in package.json.

Recommended Project Structure

src/
├── lib/
│   ├── db/
│   │   ├── neo4jClient.js
│   │   └── models/
│   │       ├── User.js
│   │       └── GraphNode.js
│   ├── auth/
│   │   ├── lucia.ts
│   │   └── luciaConfig.ts
│   └── graph/
│       └── ogm.js
├── routes/
│   ├── +layout.svelte
│   └── +page.svelte
└── app.html

Core Engineering Principles

• Explicit domain modeling with a clear Graph domain boundary and Neo4j-OGM-inspired patterns.
• Separation of concerns between UI, API, and data access layers.
• Type safety and predictable data shapes across server and client boundaries.
• Secure by default: proper auth, session handling, and access control.
• Idempotent operations and robust error handling with clear failure modes.

Code Construction Rules

• Queries must be parameterized; never interpolate user input into Cypher strings.
• Use a lightweight domain model with small, focused services rather than a monolith.
• All database access should go through a single Neo4j driver instance with connection pooling.
• Provide a typed API layer for both read and write operations.
• Keep environment-specific configuration isolated in environment variables.
• Do not bypass auth checks on protected endpoints.

Security and Production Rules

• Enable TLS termination in production; ensure cookies are HttpOnly and Secure.
• Use the least privilege for database credentials; rotate credentials regularly.
• Implement CSRF protection on mutating endpoints and validate JWTs/sessions on each request.
• Audit logs for auth events without logging secrets or payloads.
• Limit payload sizes and enforce strict rate limiting on APIs.

Testing Checklist

• Unit tests for graph domain models and utility functions.
• Integration tests for auth flows with Lucia and Neo4j sessions.
• Integration tests for graph queries using a test Neo4j instance.
• End-to-end tests for login, protected routes, and data creation flows.
• CI should run tests on a clean install and run linting as part of the pipeline.

Common Mistakes to Avoid

• Allowing string interpolation in Cypher queries (risk of injection).
• Storing secrets in client-side code or commit history.
• Skipping authentication checks on sensitive endpoints.
• Over-fetching data or exposing internal graph structure in responses.
• Neglecting tests for edge cases, especially around authentication and authorization.

FAQ

Q: What is the purpose of this CLAUDE.md Template?

A: It provides a concrete, copyable blueprint to implement a SvelteKit + Neo4j + Lucia Auth stack with Neo4j-OGM patterns, ready for Claude Code to generate boilerplate code, tests, and deployment artifacts.

Q: How do I model entities with Neo4j-OGM patterns in Node?

A: Define small domain models that map to Neo4j nodes and relationships, and expose a typed API layer that translates to parameterized Cypher statements.

Q: How do I secure authentication in this stack?

A: Use Lucia Auth with secure cookies, server-side session handling, and RBAC checks on protected routes. Do not bypass auth checks.

Q: What should I test?

A: Unit tests for domain models, integration tests for auth and data access, and end-to-end tests for login and protected operations.

Q: How do I deploy?

A: Deploy to a Node-compatible host with TLS; provide environment variables for secrets; ensure health checks and proper logging.