Persistence and Schema Reverse Engineering

Mission

Determine whether persistence exists, how code reaches it, and what schema/data model is actually supported by repository evidence.

Applicability Check

First search for:

• JDBC/data sources/connections
• ORM entities/mappings
• repository/DAO classes
• SQL/query builders
• migration frameworks/scripts
• DDL/schema files
• embedded/test DB setup
• upgrade/install scripts
• table/column constants

If no persistence is materially present, record NOT_APPLICABLE with evidence and stop.

Runtime Trace

Trace representative reads and writes:

business/service
→ repository/DAO
→ ORM/query/SQL
→ connection/data source
→ table/entity/schema

Verify runtime binding of repository implementations when abstractions exist.

Schema Reconstruction

Use evidence in priority order:

1. active migrations/DDL/schema bootstrap
2. active ORM/entity mappings
3. production SQL/query definitions
4. install/upgrade scripts
5. tests/test schema as supporting evidence only
6. docs/comments as secondary evidence

Reconstruct where supported:

• table/entity names
• important columns/fields
• data types
• PK/unique keys
• FKs/relationships
• indexes when behaviorally relevant
• read/write ownership
• transaction boundaries
• migration/version history

Do not invent missing columns or relationships.

Required Tables

Persistence Path

Schema Inventory

Schema Gaps

External Schema

If the repository contains queries/mappings but not authoritative DDL:

• promote only the schema facts directly required/proven by active code
• mark unavailable authoritative DDL/version as external if repository search is exhausted
• do not call all database schema details UNKNOWN

Output

Create/update:

docs/reverse-engineering/persistence/<scope>.md

Update evidence ledger/open questions as appropriate.

Consumer Architecture Model

Update:

docs/reverse-engineering/models/persistence_state_model.md
docs/reverse-engineering/diagrams/05_state_persistence_lifecycle.md

The model must explain ownership and behavior, not merely dump entity fields.

Capture, where applicable:

owner
→ read/write path
→ transaction/connection boundary
→ persisted entity/table/state
→ lifecycle/state transition
→ concurrency/async interaction
→ failure/recovery behavior

05_state_persistence_lifecycle.md must contain at least one evidence-linked Mermaid diagram. If persistence is not applicable, model the most material runtime state/resource/job lifecycle instead and document why persistence is NOT_APPLICABLE.