Neo4j (Web App Integration)

Last Updated: 2026-01-19

This page covers how the web app connects to Neo4j and where to find the canonical schema documentation.

Schema documentation

• Canonical graph model: Data Model
• Schema artifacts + generators: Generated Schema Artifacts

Environment variables

The web app expects:

• NEO4J_URI
• NEO4J_USERNAME
• NEO4J_PASSWORD
• NEO4J_DATABASE (optional; defaults to neo4j)

Performance / caching

• Neo4j query results should be cached at the request level when possible.
• Consider using React’s cache() wrapper for request-scoped caching.

File structure

• apps/web/src/lib/neo4j/index.ts - Main database connection and utilities
• apps/web/src/lib/neo4j/designs.ts - Design-related queries
• apps/web/src/lib/neo4j/flights.ts - Flight-related queries and operations
• apps/web/src/lib/neo4j/translation.ts - Data transformation utilities
• apps/web/src/lib/neo4j/db-types.ts - TypeScript interfaces for database entities based on the shared graph schema
• apps/web/src/types/flight.ts - Flight-specific TypeScript interfaces

Visual schema tools

The schema can be visualized/edited using Arrows.app:

1. Import data/neo4j-arrows-schema.json into https://arrows.app
2. Make changes visually
3. Export back to JSON as needed