Neo4j (Web App Integration)

Last Updated: 2026-07-07

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

Schema documentation

The web app expects:

When any of these are missing the driver helpers return null instead of throwing, so next build can evaluate modules without a database.

Reads are wrapped in React cache() for request-scoped deduplication, return null/[] when nothing matches, and let infrastructure errors bubble to the caller.
Writes throw when the operation fails.
Raw nodes are translated through translation.ts into validated application types (db-types → translation → application-types, with Zod schemas in validation.ts enforced in development).
Bulk ingestion writes (.ork design geometry, flight telemetry) happen in the data-platform lambdas (ork-processor, flight-processor), not in apps/web. The web app writes interactive data (flight shells, sources, comments, ownership relationships) and RenderJob nodes that track the flight-render pipeline (render-jobs.ts).

apps/web/src/lib/neo4j.ts - Driver singleton, executeRead/executeWrite helpers, error contract
apps/web/src/lib/neo4j/clubs.ts - Club queries
apps/web/src/lib/neo4j/designs.ts - Design queries
apps/web/src/lib/neo4j/flights.ts - Flight queries and interactive flight writes
apps/web/src/lib/neo4j/manufacturers.ts - Manufacturer queries
apps/web/src/lib/neo4j/models.ts - Model (build/"my rocket") queries and ownership checks
apps/web/src/lib/neo4j/motors.ts - Motor catalog queries
apps/web/src/lib/neo4j/render-jobs.ts - RenderJob node reads/writes for the flight-render pipeline
apps/web/src/lib/neo4j/seed-manufacturers.ts - Manufacturer seeding utilities
apps/web/src/lib/neo4j/db-types.ts - Database-shaped TypeScript interfaces based on the shared graph schema
apps/web/src/lib/neo4j/application-types.ts - Application-level types (Zod-inferred)
apps/web/src/lib/neo4j/translation.ts - Node → application-type translators
apps/web/src/lib/neo4j/validation.ts - Zod schemas and validation wrappers
apps/web/src/types/flight.ts - Flight-specific TypeScript interfaces

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