|
|
|
@@ -0,0 +1,149 @@
|
|
|
|
|
# Project History and External Model Architecture
|
|
|
|
|
|
|
|
|
|
## Status
|
|
|
|
|
|
|
|
|
|
This document records architectural direction for future work. It is not a final database schema and does not authorize implementing Revit exchange or migrating to PostgreSQL during unrelated phases.
|
|
|
|
|
|
|
|
|
|
## Goals
|
|
|
|
|
|
|
|
|
|
- persist undo/redo across page reloads and application restarts
|
|
|
|
|
- provide a project-wide version history with named restore points
|
|
|
|
|
- preserve an auditable sequence of user, import, migration and restore operations
|
|
|
|
|
- support future Revit/CSV round-trips using stable IFCGUID-based links
|
|
|
|
|
- keep the persistence boundary replaceable so PostgreSQL can be adopted later
|
|
|
|
|
|
|
|
|
|
## Separate Concerns
|
|
|
|
|
|
|
|
|
|
The following mechanisms solve different problems and must not be conflated:
|
|
|
|
|
|
|
|
|
|
- database backups protect against database loss or corruption
|
|
|
|
|
- project snapshots provide user-visible restore points
|
|
|
|
|
- change history records logical application operations
|
|
|
|
|
- undo/redo navigates or inverses eligible logical operations
|
|
|
|
|
- external import batches describe data exchanged with another model
|
|
|
|
|
|
|
|
|
|
Database backups remain necessary even after project version history exists.
|
|
|
|
|
|
|
|
|
|
## Revision and Change-Set Direction
|
|
|
|
|
|
|
|
|
|
History is project-wide. Every accepted mutating command should eventually execute through one server-side transaction that:
|
|
|
|
|
|
|
|
|
|
1. validates the expected current project revision
|
|
|
|
|
2. applies all domain writes
|
|
|
|
|
3. records one immutable change set with sufficient before/after data
|
|
|
|
|
4. increments the project revision
|
|
|
|
|
|
|
|
|
|
The conceptual entities are:
|
|
|
|
|
|
|
|
|
|
- `ProjectRevision`
|
|
|
|
|
- monotonically increasing revision number within one project
|
|
|
|
|
- timestamp, actor and source (`user`, `undo`, `redo`, `import`, `restore`, `migration`)
|
|
|
|
|
- optional label or description
|
|
|
|
|
- `ProjectChangeSet`
|
|
|
|
|
- one logical user or system command
|
|
|
|
|
- contains one or more domain operations committed atomically
|
|
|
|
|
- stores enough before/after state to validate and apply an inverse
|
|
|
|
|
- `ProjectSnapshot`
|
|
|
|
|
- a logical, database-independent representation of one project revision
|
|
|
|
|
- may be created periodically or explicitly named by a user
|
|
|
|
|
- accelerates restore without replaying the entire history
|
|
|
|
|
|
|
|
|
|
Full event sourcing is not required. Current normalized tables remain the primary read model. Immutable change sets plus periodic snapshots provide the required history without forcing every query to rebuild state from events.
|
|
|
|
|
|
|
|
|
|
## Undo, Redo and Restore Semantics
|
|
|
|
|
|
|
|
|
|
- Undo applies an inverse as a new recorded revision; it does not delete history.
|
|
|
|
|
- Redo reapplies an eligible undone operation as a new recorded revision.
|
|
|
|
|
- A new edit after undo may hide the prior redo branch in the normal UI, while the historical revisions remain auditable.
|
|
|
|
|
- Restoring a snapshot creates a new revision whose state matches the selected historical revision.
|
|
|
|
|
- The server, not React component state, is the source of truth for available undo/redo operations.
|
|
|
|
|
- After a page reload, the client requests the current revision and eligible history actions.
|
|
|
|
|
- Commands include an expected project revision. A stale command is rejected instead of silently overwriting a newer project state.
|
|
|
|
|
|
|
|
|
|
The current session-local frontend command stack is transitional. Editor modularization must separate command descriptions from React callbacks so commands can later be sent to and reconstructed by the server.
|
|
|
|
|
|
|
|
|
|
## Snapshot Storage
|
|
|
|
|
|
|
|
|
|
Project history must use logical project data, not copies of the SQLite database file. This keeps snapshots:
|
|
|
|
|
|
|
|
|
|
- project-scoped
|
|
|
|
|
- portable across SQLite and PostgreSQL
|
|
|
|
|
- independent from unrelated projects
|
|
|
|
|
- suitable for validation, comparison and selective restore tooling
|
|
|
|
|
|
|
|
|
|
Large snapshots may later be compressed or stored in object storage, with metadata and checksums retained in the database.
|
|
|
|
|
|
|
|
|
|
## Revit / CSV / IFCGUID Round-Trip Direction
|
|
|
|
|
|
|
|
|
|
External model exchange should use explicit staging and link entities instead of writing imported rows directly into circuits.
|
|
|
|
|
|
|
|
|
|
Conceptual entities:
|
|
|
|
|
|
|
|
|
|
- `ExternalModelSource`
|
|
|
|
|
- identifies a Revit/IFC model or another external source within a project
|
|
|
|
|
- `ExternalImportBatch`
|
|
|
|
|
- file name, checksum, import time, format/version and processing status
|
|
|
|
|
- `ExternalModelObject`
|
|
|
|
|
- stable IFCGUID and optional Revit element identifiers
|
|
|
|
|
- source attributes and last-seen import batch
|
|
|
|
|
- `ExternalObjectLink`
|
|
|
|
|
- explicit relationship to a project device, circuit device row or another future domain entity
|
|
|
|
|
- `ExternalParameterMapping`
|
|
|
|
|
- maps imported/exported columns to application fields
|
|
|
|
|
- `ExternalExportBatch`
|
|
|
|
|
- records which project revision and import source produced an exported file
|
|
|
|
|
|
|
|
|
|
Required behavior:
|
|
|
|
|
|
|
|
|
|
- IFCGUID uniqueness is scoped to project and external model source.
|
|
|
|
|
- Parsing writes to staging first.
|
|
|
|
|
- Users preview additions, changes, missing objects and conflicts before applying them.
|
|
|
|
|
- Applying an import creates one project revision and one auditable change set.
|
|
|
|
|
- Imported source values and locally assigned planning values remain distinguishable.
|
|
|
|
|
- Export retains IFCGUID and source identifiers so Revit parameters can be matched deterministically.
|
|
|
|
|
- Missing objects and duplicate/conflicting identifiers are reported, never silently reassigned.
|
|
|
|
|
|
|
|
|
|
## SQLite and PostgreSQL Direction
|
|
|
|
|
|
|
|
|
|
SQLite remains appropriate for the current local, single-process development workflow and can handle initial external-object volumes. Data volume alone is not a reason to migrate immediately.
|
|
|
|
|
|
|
|
|
|
PostgreSQL becomes appropriate when one or more of these conditions apply:
|
|
|
|
|
|
|
|
|
|
- multiple users edit projects concurrently
|
|
|
|
|
- the API runs as a shared network service
|
|
|
|
|
- background import/export jobs need independent workers
|
|
|
|
|
- revision/history queries or external-object datasets need server-side concurrency and operational tooling
|
|
|
|
|
- centralized backup, access control and monitoring become required
|
|
|
|
|
|
|
|
|
|
To preserve that option:
|
|
|
|
|
|
|
|
|
|
- domain services must not depend directly on `better-sqlite3`
|
|
|
|
|
- new multi-write workflows use an injectable transaction/unit-of-work boundary
|
|
|
|
|
- database-generated behavior is kept behind repositories
|
|
|
|
|
- IDs remain stable UUIDs and revisions use explicit project-scoped sequence numbers
|
|
|
|
|
- history snapshots remain logical and database-independent
|
|
|
|
|
- SQLite-specific synchronous transaction callbacks are treated as an adapter detail
|
|
|
|
|
- real persistence tests are separated so PostgreSQL parity tests can be added later
|
|
|
|
|
|
|
|
|
|
Drizzle schemas and migrations are dialect-specific and will require a deliberate PostgreSQL schema/migration path. The goal is portable domain behavior, not pretending the current database schema files can be switched without work.
|
|
|
|
|
|
|
|
|
|
## Near-Term Refactoring Constraints
|
|
|
|
|
|
|
|
|
|
Before implementing the future features:
|
|
|
|
|
|
|
|
|
|
- add real SQLite rollback tests around the persistence boundary
|
|
|
|
|
- stop adding direct imports of the global SQLite client to domain services
|
|
|
|
|
- extract transaction ownership from oversized repositories incrementally
|
|
|
|
|
- modularize editor history commands independently from UI rendering
|
|
|
|
|
- preserve stable domain IDs during legacy cleanup
|
|
|
|
|
- do not model IFCGUID as an overloaded circuit equipment identifier
|
|
|
|
|
- keep database backup/restore checks separate from project history tests
|
|
|
|
|
|
|
|
|
|
## Deferred Decisions
|
|
|
|
|
|
|
|
|
|
- exact snapshot frequency and retention policy
|
|
|
|
|
- whether large snapshot payloads remain in PostgreSQL or move to object storage
|
|
|
|
|
- branch visualization after undo followed by new edits
|
|
|
|
|
- user/role model and actor attribution
|
|
|
|
|
- supported Revit CSV dialects and parameter mapping UI
|
|
|
|
|
- PostgreSQL deployment topology and migration date
|
