Generated Schema Artifacts

Auto-generated files from the Neo4j AuraDB database.

Source of Truth

Neo4j AuraDB - The live database is the single source of truth for schema.

Schema is exported using APOC procedures and used to generate TypeScript types and Zod schemas.

Directory Structure

generated/
├── cypher/
│   ├── schema-export.cypher    # Full schema export from APOC
│   └── constraints.cypher      # Extracted constraints only
├── types/
│   └── neo4j-types.ts          # TypeScript node/relationship types
└── schemas/
    └── neo4j-schemas.ts        # Zod validation schemas

Generated Files

Regenerate

Use Prefect tasks to regenerate all artifacts from Neo4j:

from tasks.schema import export_schema_from_neo4j, get_schema_metadata

# Export schema from Neo4j
result = export_schema_from_neo4j()
print(f"Exported to: {result['schema_export']}")

# Get metadata for type generation
metadata = get_schema_metadata()
print(f"Found {len(metadata['nodes'])} node types")

Or run the tasks directly:

python tasks/schema/export_from_neo4j.py

Workflow

When schema changes in Neo4j:

1. Update Neo4j database (apply migrations, add constraints, etc.).
2. Export schema from Neo4j:
   • uv run python -m tasks.schema.export_from_neo4j
3. Generate TypeScript types:
   • uv run python -m tasks.schema.generate_typescript
4. Generate Zod schemas:
   • uv run python -m tasks.schema.generate_zod
5. Resulting artifacts (committed to this repo):
   • generated/types/neo4j-types.ts
   • generated/schemas/neo4j-schemas.ts
6. Schema package source (kept in sync by the same generators):
   • schema-package/src/neo4j-types.ts
   • schema-package/src/neo4j-schemas.ts

These source files are the authored source of the schema package @rocketclub/rocketry-graph-schema, consumed at source, at build time — not published to a registry.

Schema package & how it's consumed

Schema-first, authored at source. Per ADR-0004 and ADR-0005, the schema package is private: true and consumed at source at build time — it is not published to GitHub Packages, and the S3-versioned publish-schema-package flow (which lived only in the external blog_data repo's CI) is retired. See Rocketry Graph Schema Publishing Pipeline for that retired mechanism.

Package location & contents

• Package directory: data/platform/schema-package/ (Nx lib rocketry-graph-schema)
• Package name: @rocketclub/rocketry-graph-schema (private: true, main/types → src/index.ts)
• Public entrypoint:
  • schema-package/src/index.ts re-exports:
    • ./neo4j-types
    • ./neo4j-schemas

The Python generators write to both generated/... and schema-package/src/..., so the package source always reflects the latest Neo4j schema.

Consuming the package (e.g. in the web app, apps/web)

Consumers resolve the package at source — no registry, no npm publish:

• apps/web imports @rocketclub/rocketry-graph-schema, which tsconfig.base.json maps to data/platform/schema-package/src and Jest maps via moduleNameMapper.
• The Lambdas (e.g. data/platform/lambda/ork-processor) depend on it via a local file:../../schema-package reference.

import {
  Neo4jNode,
  Neo4jRelationship,
  Neo4jNodeSchema,
  Neo4jRelationshipSchema,
} from '@rocketclub/rocketry-graph-schema';

Notes

• Yes Neo4j AuraDB is the source of truth
• No DO NOT manually edit generated files
• Yes DO use Prefect tasks to regenerate after schema changes
• Yes DO commit generated files to version control

Migration from graph-schema.json

The old graph-schema.json approach has been deprecated in favor of using Neo4j directly:

• Old approach: Manually maintain graph-schema.json → Generate artifacts
• New approach: Neo4j AuraDB → Export via APOC → Generate artifacts

Benefits:

• No drift between JSON and database
• Always up-to-date with current schema
• Captures all constraints and indexes automatically