Remix Framework + Neo4j Graph Database + Firebase Auth + Neo4j-OGM Configuration | CLAUDE.md Template

Overview

Direct answer: This CLAUDE.md Template provides a complete blueprint to implement a Remix frontend with Neo4j Graph Database, Firebase Auth, and a backend configured with Neo4j-OGM for data mapping. The page includes a copyable CLAUDE.md block you can paste into Claude Code to scaffold the stack.

The template targets Remix Framework for the frontend, a Java Spring-based backend using Neo4j-OGM, and a secure integration withFirebase Auth.

When to Use This CLAUDE.md Template

• When you are building a Remix application that uses Neo4j as the graph database for domain models and relationships.
• When you want Firebase Auth to manage user authentication on the client and verify tokens on the backend.
• When you use Neo4j-OGM in a Java backend to map domain models to graph data.
• When you want a cohesive project structure with frontend-backend separation and clear deployment rules.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a Remix frontend engineer and a Java Spring backend engineer who will wire Remix to a Neo4j graph database via Neo4j-OGM, secured by Firebase Auth. Produce production-ready skeletons and inline explanations that Claude Code can paste directly.

Architecture rules:
- Frontend: Remix app; Backend: Spring Boot with Neo4j-OGM; Graph DB: Neo4j.
- All API calls from Remix to backend must include a valid Firebase ID token in Authorization: Bearer  headers.
- Backend validates tokens using Firebase Admin SDK on protected routes.
- Do not call Neo4j directly from Remix; go through the backend API layer.
- Use environment variables for credentials; never hardcode secrets.

File structure rules:
- Do not mix frontend and backend source folders.
- Place Remix project under apps/remix-app and Java backend under backend-spring.
- Keep a single source of truth for DB models in the backend module.

Authentication rules:
- Frontend obtains Firebase ID tokens after user login and forwards them in API requests.
- Backend must verify the token on every protected endpoint and reject invalid tokens with 401.
- Use role checks in backend (e.g., USER, ADMIN) where appropriate.

Database rules:
- Neo4j must run with Bolt port 7687; TLS in production.
- Neo4j-OGM mappings declared via Java annotations; keep models in com.example.neo4jogm.models.
- Use parameterized Cypher to avoid injection; never concatenate strings for queries.

Validation rules:
- Validate and sanitize input DTOs before mapping to domain entities.
- Use bean validation where applicable; return 400 on validation errors.

Security rules:
- Do not reveal database credentials to the client.
- Do not emit full stack traces in production.
- Encrypt sensitive environment variables and rotate secrets regularly.

Testing rules:
- Backend: unit tests for services and repositories; integration tests for token verification and DB operations.
- Frontend: basic component tests and integration tests for API calls.
- End-to-end tests should cover login and data fetch flows.

Deployment rules:
- Provide Docker Compose for local dev with a Neo4j container and a Spring Boot backend.
- For prod, provide Kubernetes manifests and a secure Ingress.
- Ensure CI runs schema migrations and linting.

Things Claude must not do:
- Do not bypass authentication or authorization checks.
- Do not access Neo4j directly from Remix routes.
- Do not store or log credentials in plaintext.

Recommended Project Structure

remix-neo4j-firebase-ogm-claude-md-template/
├── apps/
│   └── remix-app/
│       ├── package.json
│       ├── remix.config.js
│       ├── app/
│       │   ├── root.jsx
│       │   └── routes/
│       │       └── index.jsx
│       └── .env.example
├── backend-spring/
│   ├── pom.xml
│   └── src/
│       ├── main/
│       │   ├── java/
│       │   │   └── com/example/neo4jogm/
│       │   │       ├── controllers/
│       │   │       ├── models/
│       │   │       ├── repositories/
│       │   │       └── Neo4jConfig.java
│       │   └── resources/
│       │       └── application.yml
│       └── test/
│           └── java/
└── infra/
    ├── docker-compose.yml
    └── neo4j.conf

Core Engineering Principles

• Clear separation of concerns between Remix frontend and Java backend.
• Single source of truth for data models in the backend (Neo4j-OGM).
• Explicit contracts between layers via REST endpoints and DTOs.
• Strong typing and validation for all inputs.
• Automated tests for units, integration, and end-to-end flows.

Code Construction Rules

• Claude Code must generate a Remix frontend that calls backend APIs over HTTPS.
• Backend must verify Firebase tokens on protect routes and extract user identity from tokens.
• Neo4j-OGM domain models must be annotated and placed under com.example.neo4jogm.models.
• Queries must use parameter binding; avoid string concatenation in Cypher.
• Secrets must be read from environment variables; never hard-coded.

Security and Production Rules

• Token verification is mandatory for all protected endpoints.
• Use TLS in production, and restrict Neo4j exposure to necessary networks.
• Rotate credentials and enable secret management in CI/CD.

Testing Checklist

• Backend: unit tests for services and repositories.
• Integration tests for token verification and graph queries.
• Frontend: component and API integration tests.
• CI should run lint, tests, and basic end-to-end checks.

Common Mistakes to Avoid

• Exposing backend secrets to the client.
• Directly calling Neo4j from Remix routes.
• Skipping token verification on protected endpoints.

FAQ

What stack does this CLAUDE.md Template target?

Remix frontend, Neo4j Graph DB, Firebase Auth, and Neo4j-OGM backend.

What should Claude Code output?

A complete copyable CLAUDE.md file with stack-specific instructions.

How is authentication handled?

Frontend uses Firebase Auth; backend verifies Firebase tokens via the Firebase Admin SDK.

Where is the Neo4j-OGM config located?

In the Java backend, using Neo4j-OGM annotations and a dedicated configuration class.

Where should I place the project structure?

Frontend under apps/remix-app and backend under backend-spring; use docker-compose for dev and k8s for prod.