64 lines
2.6 KiB
Markdown
64 lines
2.6 KiB
Markdown
---
|
|
description: How to safely refine the data model, update migrations, and keep data generation and tests in sync
|
|
---
|
|
|
|
# Data Model Refinement & Synchronisation Workflow
|
|
|
|
This workflow ensures every data model change is robust, consistent, and reflected across migrations, documentation, data generation, and tests.
|
|
|
|
---
|
|
|
|
## 1. Reference the Authoritative Sources
|
|
|
|
Before making or reviewing any data model change, consult these key documents:
|
|
|
|
- `/docs/solution-architecture.md` — **PRIMARY**: Comprehensive solution architecture and design decisions
|
|
- `/docs/dataModel/README.md` — Data model documentation and ERD
|
|
- `/local-dev-setup/liquibase/changelogs/001_unified_baseline.sql` — Baseline schema (Liquibase)
|
|
- `/docs/adr/` — Current ADRs (skip `/docs/adr/archive/` - consolidated in solution-architecture.md)
|
|
|
|
## 2. Plan the Change
|
|
|
|
- Identify the business or technical rationale for the change.
|
|
- Determine the impact on existing tables, columns, relationships, and constraints.
|
|
- Draft or update the ERD as needed.
|
|
|
|
## 3. Update the Schema
|
|
|
|
- Create or edit the appropriate Liquibase changelog(s) (never edit the baseline directly after project start).
|
|
- Follow naming conventions and migration strategy as per ADRs.
|
|
- Document every change with clear comments in the changelog.
|
|
|
|
## 4. Update Data Model Documentation
|
|
|
|
- Reflect all changes in `/docs/dataModel/README.md` (ERD, field lists, rationale).
|
|
- If the change is significant, consider updating or creating an ADR.
|
|
|
|
## 5. Synchronise Data Generation Scripts
|
|
|
|
- Review and update `local-dev-setup/data-utils/umig_generate_fake_data.js` (FAKER-based generator).
|
|
- Adjust or add generators in `local-dev-setup/data-utils/generators/` as needed.
|
|
- Ensure all generated data matches the new/updated schema.
|
|
|
|
## 6. Update and Extend Tests
|
|
|
|
- Update all related tests in `local-dev-setup/data-utils/__tests__/` to cover new/changed fields and relationships.
|
|
- Add new fixture data if needed.
|
|
- Ensure tests remain non-destructive and deterministic.
|
|
|
|
## 7. Validate
|
|
|
|
- Run all migrations in a fresh environment (dev/test).
|
|
- Run the data generation script and all tests; confirm no failures or regressions.
|
|
- Review the ERD and documentation for completeness and accuracy.
|
|
|
|
## 8. Document and Communicate
|
|
|
|
- Update `CHANGELOG.md` with a summary of the data model change.
|
|
- If required, update the main `README.md` and any relevant ADRs.
|
|
- Consider adding a Developer Journal entry to narrate the rationale and process.
|
|
|
|
---
|
|
|
|
> _Use this workflow every time you refine the data model to maintain project discipline, testability, and documentation integrity._
|