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 bundled and published as the npm package @rlhatcher/rocketry-graph-schema to GitHub Packages.

Schema npm package & CI publish flow

Package location & contents

• Package directory: schema-package/
• Package name: @rlhatcher/rocketry-graph-schema
• 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 npm package always reflects the latest Neo4j schema.

Publishing to GitHub Packages (manual steps)

1. Ensure schema has been regenerated (steps above).
2. Bump the npm version inside schema-package:
   • cd schema-package
   • npm version patch # or minor/major as appropriate
3. Commit the version bump in blog_data:
   • git add schema-package/package.json
   • git commit -m "Bump schema package to <version>"
4. Tag the commit to trigger CircleCI publish:
   • git tag schema-v<version> (e.g. schema-v0.1.1)
   • git push origin main
   • git push origin schema-v<version>

CircleCI workflow publish-schema-package-wf will:

• Use the aws-blog-infra-prod context.
• Assume OrganizationAccountAccessRole via STS.
• Fetch the GitHub PAT from AWS Secrets Manager secret prod/github/pat/blog_data_ci.
• Configure npm auth for https://npm.pkg.github.com.
• Run npm publish inside schema-package.

Consuming the package (other repos, e.g. blog_code)

1. Configure npm scope for GitHub Packages (repo-local .npmrc):

   @rlhatcher:registry=https://npm.pkg.github.com
   

2. Add dependency (example package.json excerpt):

   {
     "dependencies": {
       "@rlhatcher/rocketry-graph-schema": "^0.1.0"
     }
   }
   

3. Use in TypeScript:

   import {
     Neo4jNode,
     Neo4jRelationship,
     Neo4jNodeSchema,
     Neo4jRelationshipSchema
   } from '@rlhatcher/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