File Lifecycle

This page makes the file ownership boundary explicit:

• which files you write yourself
• which files are generated
• which tool generates them
• which tool or runtime consumes them later
• which files are safe to edit manually

The short version is:

• write source files that describe your models and export workflow
• optionally write a schema metadata config file for richer encrypted object types
• do not hand-edit generated manifest or client binding outputs
• review generated database diff output before applying it

Recommended Layout

One common layout looks like this:

generated/
  expected-schema.json
  e2ee-client-bindings.ts
  schema-diff.sql
scripts/
  generate-e2ee-bindings.mjs
e2ee-backend.db-schema.json
e2ee-backend.encrypted-schema.json
generated/e2ee-backend.manifest.json

The exact paths are up to you. What matters is which file is the source of truth and which files are generated artifacts.

File Matrix

File	Usually created by	Consumed by	Manual edits allowed?	Notes
scripts/generate-e2ee-bindings.mjs or equivalent source file	You	Your own build or generation workflow	Yes	This is still a real source file, but it should just invoke e2ee-backend-adapter-cli with the DB schema file plus the encrypted schema overlay.
e2ee-backend.db-schema.json	CLI + database	e2ee-backend-adapter-cli export-expected-schema --db-schema-config ...	Usually no	Structural generated file containing table metadata, inferred field shapes, and encrypted field placeholders.
e2ee-backend.encrypted-schema.json	You	e2ee-backend-adapter-cli export-expected-schema --encrypted-schema-config ...	Yes	User-authored overlay for encrypted field structure and API naming overrides.
generated/e2ee-backend.manifest.json	Your generator script, using e2ee-client-backend	e2ee-backend-adapter-server, e2ee-backend-adapter-cli validate-manifest, e2ee-backend-adapter-cli diff, e2ee-backend-adapter-cli export-expected-schema	No	Generated artifact. If something is wrong, change the source generator code, not this file.
generated/expected-schema.json	e2ee-backend-adapter-cli export-expected-schema	Client apps that consume generated schema JSON directly	No	Generated artifact. It is client-facing schema metadata, not runtime server input.
generated/e2ee-client-bindings.ts	e2ee-backend-adapter-cli export-expected-schema --typescript-out ...	TypeScript apps using generated typed helpers	No	Generated artifact. Import this in your frontend or client package instead of rewriting types and transport wiring manually.
generated/schema-diff.sql	e2ee-backend-adapter-cli diff	You, your migration workflow, or database tooling	Yes, with review	Generated starting point. Review before applying to a real database.
migration/src/...rs created with --format seaorm	e2ee-backend-adapter-cli diff --format seaorm	Your migration crate and deployment pipeline	Yes, with review	Generated scaffold. You may refine it before running it.

User-Owned Source Files

These are the files you should treat as primary source files.

DB Schema Config File

This is the file passed through --db-schema-config.

Typical responsibilities:

• define backend/entity names and DB mappings
• define inferred non-encrypted field schemas from DB metadata
• mark encrypted field placeholders and transport paths

This file is generated from the database and should usually not be edited by hand.

Encrypted Schema Config File

This is the file passed through --encrypted-schema-config.

Typical responsibilities:

• define reusable named schema fragments in types
• map encrypted fields to logical decrypted object structures
• add API naming overrides when your backend does not follow adapter defaults

This file is also owned by you and should be edited directly.

Use it when a field like config should generate as a structured object type instead of a fallback like Record<string, unknown>.

The DB file can be scaffolded from Postgres with generate-db-schema-config.

Generated Files

These are outputs. They are not the source of truth.

e2ee-backend.manifest.json

Generated by your own source file, usually using e2ee-client-backend manifest helpers.

Consumed by:

• e2ee-backend-adapter-server
• e2ee-backend-adapter-cli validate-manifest
• e2ee-backend-adapter-cli diff
• e2ee-backend-adapter-cli export-expected-schema

Do not hand-edit it. If you need different routes, fields, table names, or API metadata, change the source generator code and regenerate.

expected-schema.json

Generated by e2ee-backend-adapter-cli export-expected-schema.

Consumed by:

• generated-schema clients that work from JSON
• tooling that wants a portable description of the client-facing expected schema

It is not consumed by the runtime server. It is not a migration file. It should not be edited manually.

e2ee-client-bindings.ts

Generated by e2ee-backend-adapter-cli export-expected-schema --typescript-out.

Consumed by:

• TypeScript client applications
• frontend code that wants generated auth helpers, typed entities, adapters, and entity schema builders

It should not be edited manually. If the generated types are wrong, change the generator source or the schema config file and regenerate.

Database Diff Outputs

The diff outputs are different from the generated schema files.

They are generated artifacts, but unlike the manifest and client bindings, they are usually expected to be reviewed before use.

SQL Diff Output

Generated by:

e2ee-backend-adapter-cli diff \
  --manifest ./generated/e2ee-backend.manifest.json \
  --database-url postgres://postgres:postgres@localhost:5432/app \
  --out ./generated/schema-diff.sql

Consumed by:

• you
• your database deployment workflow
• a DBA or migration review process

Manual edits are allowed, and review is recommended.

SeaORM Migration Scaffold

Generated by:

e2ee-backend-adapter-cli diff \
  --format seaorm \
  --manifest ./generated/e2ee-backend.manifest.json \
  --database-url postgres://postgres:postgres@localhost:5432/app \
  --out ./migration/src/m20260503_000001_sync_manifest.rs

Consumed by:

• your migration crate
• your application deployment process

Manual edits are allowed, and review is recommended.

What To Edit When Something Looks Wrong

If the runtime server behavior is wrong:

• edit the manifest generator source file
• then regenerate e2ee-backend.manifest.json

If generated client types for encrypted fields or binding operation names are wrong:

• edit e2ee-backend.encrypted-schema.json
• then rerun export-expected-schema

If a generated SQL or migration file needs cleanup before applying:

• edit the generated diff output directly
• keep in mind that a future diff run may overwrite that file unless you store it in a reviewed migration location

Source Of Truth Rules

• Treat the DB schema config file as the source of truth for generated table, entity, and inferred field metadata.
• Treat the encrypted schema config file as the source of truth for richer decrypted object metadata and API naming overrides.
• Treat generated manifest and generated client binding files as disposable build artifacts unless your repository intentionally commits them.
• Treat generated diff output as a reviewed starting point, not an untouchable artifact.