ICT:Data Model Overview v 4.0
Data Model Overview version 4.0
This page provides a structured overview of the Costasano Heritage Database data model and its supporting technical documentation.
It serves as the primary entry point for:
- system maintainers
- future developers
- data architects
- project successors
The goal is to explain how the model is organized and where detailed specifications can be found.
Purpose
The data model separates clearly between:
- conceptual meaning
- logical structure
- technical implementation
Documentation follows the same separation.
This prevents:
- semantic confusion
- accidental misuse of entities
- implementation-driven design decisions
- loss of knowledge over time
Conceptual architecture
The system models five distinct concerns:
| Concern | Responsibility | Entities |
|---|---|---|
| Storage | physical files only | File |
| Interpretation / sources | scholarly description of files | DigitalAsset |
| Subjects of research | historical actors and objects | HeritageObject, Person, Organization |
| Spatial context | where things exist or occur | Place |
| Narrative structure | interpretation and storytelling | ResearchChapter |
The fundamental conceptual flow is:
File → DigitalAsset → Research Entity → Place → ResearchChapter
Each layer has a single responsibility.
No entity should take over the responsibility of another.
Documentation structure
The documentation is divided into four complementary parts.
They must be read in order when learning the system.
1. Entity Definitions (conceptual layer)
Defines meaning and responsibility of each entity.
Answers:
- What is this concept?
- What does it represent?
- What is it NOT?
This document is authoritative for semantics.
ICT:Data Model – Entity Definitions
2. Conceptual ER Diagram (visual layer)
Technology-independent diagram of the domain model.
Shows:
- entities
- main relationships
- hierarchy
- responsibilities
Does NOT include:
- junction tables
- lookup tables
- technical details
Used for understanding and discussion.
3. DBML / Cargo Schema (logical layer)
Defines the implementable database structure.
Includes:
- tables
- fields
- foreign keys
- junction tables
- lookup tables
Translates the conceptual model into a concrete schema.
4. Identifier Strategy (operational layer)
Defines rules for:
- page names
- numbering
- automatic identifiers
- file naming
Ensures consistency and long-term stability of records.
ICT:Identifier and Numbering Strategy
Design principles
The model follows these principles:
Separation of concerns
Each entity has one clear responsibility.
Examples:
- Files store data
- DigitalAssets interpret files
- Organizations act
- Places locate
- Chapters structure interpretation
Conceptual first
Meaning is defined before implementation.
If an entity definition is unclear, implementation must be postponed.
Stable identifiers
Identifiers are:
- automatic
- mechanical
- uniform
They are labels only and must not encode interpretation.
Minimal semantics in structure
Complex interpretation belongs in:
- notes
- descriptions
- citations
Not in:
- flags
- scores
- overloaded entity types
Technology independence
The conceptual model must remain valid even if:
- Cargo is replaced
- MediaWiki is replaced
- storage changes
Only the logical schema is technology-specific.
Typical maintenance workflow
When extending the system:
- Update Entity Definitions first
- Update Conceptual Diagram if relationships change
- Update DBML schema
- Update Page Forms / Cargo tables
- Document the change here if architectural
For future maintainers
If unsure about a design decision:
1. Read the Entity Definitions 2. Check the conceptual diagram 3. Avoid mixing responsibilities between entities 4. Prefer adding a new concept over overloading an existing one
Clarity is more important than short-term convenience.
Status
This page summarizes the current architecture – Version 4.0.
All technical implementations must conform to the conceptual definitions and documentation linked above.