Jump to content

ICT:Drupal Blueprint - Version 6.5: Difference between revisions

From Costa Sano MediaWiki
No edit summary
No edit summary
 
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Costasano Heritage Project — Drupal 11 Architecture & Workflow Blueprint (v5.2) =
= Costasano Heritage Project — Drupal 11 Architecture & Workflow Blueprint (v6.5) =


== Purpose of this Document ==
== Purpose of this Document ==
Line 15: Line 15:
== Project Overview ==
== Project Overview ==


The Costasano Heritage Project is a long-term digital heritage initiative operated by members of the Costa Sano Club (70+ years old, amateur historians, non-ICT specialists).
The Costasano Heritage Project is a long-term digital heritage initiative operated by members of the Costa Sano Club (70+ years old, amateur historians, non-ICT specialists, except for Martin, realising the IT-project, also amateur historian).


The project manages:
The project manages:
Line 30: Line 30:
=== Authoritative Source Principle ===
=== Authoritative Source Principle ===
There is exactly ONE authoritative system for data and assets:
There is exactly ONE authoritative system for data and assets:
* '''Drupal 11'''
* '''Drupal 11.3'''


All other outputs (MediaWiki, public website, video, exhibitions) are derivatives.
All other outputs (MediaWiki, public website, video, exhibitions) are derivatives.
Line 86: Line 86:


=== Infrastructure ===
=== Infrastructure ===
* Reverse Proxy: Windows Server (IIS + ARR, SSL offloading)
* Reverse Proxy: Windows Server 2019 (IIS + ARR, SSL offloading)
* Web Server: AlmaLinux 10.1 (Apache 2.4, PHP 8.3, PHP-FPM)
* Web Server: AlmaLinux 10.1 (Apache 2.4.63, PHP 8.3.29, PHP-FPM)
* Database Server: AlmaLinux 10.1 (MariaDB 10.11+)
* Database Server: AlmaLinux 10.1 (MariaDB 10.11.15)
* Drupal 11.3.5
* SELinux: Enforcing
* SELinux: Enforcing
* PHP-FPM: Per-site pools
* PHP-FPM: Per-site pools
Line 139: Line 140:


Authority entities are implemented progressively, from simplest to most complex.   
Authority entities are implemented progressively, from simplest to most complex.   
This order is mandatory.


----
----
Line 152: Line 152:


Characteristics:
Characteristics:
* stable Code (max 6 characters) like CHxx.y CH01, CH01.1
* stable Code (max 6 characters) like CHxx.ab CH01, CH01a, CH01aa, CH01ab
* recursive (parent/child) one level only
* recursive (parent/child) two levels using small letters after the first four
* stable Code (max 6 characters)
* stable Code (max 6 characters)
* used as first mandatory component in asset identifiers
* used as first mandatory component in asset identifiers
Line 164: Line 164:


Status: Drupal Context Type and Dashboard page operational
Status: Drupal Context Type and Dashboard page operational
ToDO: -
Changed decision about chapter code layout
 
ToDo (max 6 characters)
----
 
=== Step 2: Place (Spatial Authority) ===
Type:
* '''Drupal Custom Content Entity (authority)'''
 
Characteristics:
* recursive (parent places)
* stable Code (max 6 characters)
* Address field for geocoding
* Address field for geocoding
* coordinates auto-derived when possible
* coordinates auto-derived when possible
Line 185: Line 176:


Status: Drupal Context Type and Dashboard page operational
Status: Drupal Context Type and Dashboard page operational
ToDO:  
Recently added: type list, geo link in view towards openstreetmap
# adding geocoordinnates from address in input page
Added view adapted to type.
# adding map view based on coordinnates
Address to coordinates implemented using Openstreatmap providers.
ToDo:Completing helpfunctions


----
----
Line 205: Line 197:


Status: Drupal Context Type and Dashboard page operational
Status: Drupal Context Type and Dashboard page operational
ToDO:  
ToDo: adding map view based on Place coordinnates now that provider is available
# adding map view based on Place coordinnates
Completing help functions


----
----
Line 224: Line 216:
* Chapter.Code
* Chapter.Code
* Context.Code = Place.Code OR Organisation.Code
* Context.Code = Place.Code OR Organisation.Code
* Scoped 4-digit counter (asset sequence only)
* Scoped 5-digit counter (asset sequence only)


Example:
Example:
<pre>
<pre>
CH03-OOSTEN-0007
CH03ab-OOSTEN-00007
</pre>
</pre>


Asset creation is impossible before Chapter, Place, and Organisation exist.
Asset creation is impossible before Chapter, Place, and Organisation exist.


Status: Drupal Context Type and Dashboard page operational with minimal set of attributes
Status: Drupal Context Type and View complete
ToDO:  
Use of special configuration of classic Media-Library for media upload.
# adding supplementary attributes
Upload of images, documents, video and audio foreseen
# adding automatic numbering for asset
Automatic numbering for asset via a custom module
Creation in 2 steps: first essential fields to generate autonumbering.
After that, use of editing via table to fill un further fields like description and note.
Optional change of other fields except autocode.
View enhanced with search filter.
ToDo: complete help functions
Remark: Inital configuration with Code as PK (Drupal Title) has been abandoned.
Now Code is a classic field and the Title field is a Caption field. This is a short description of the file.
 
== Next Major step: Person and HeritageObject and the m-m relationship with Asset ==
 
=== Step 5: Person implementation ===
 
A '''Person''' represents a historical individual with agency.
 
It answers the question:
 
''“Who was involved historically?”''
 
A person is:
 
* religious sisters
* directors
* architects
* patients
* shareholders
* board members
 
A Person may:
 
* play roles in relation to HeritageObjects
* play roles within Organizations
* act as a holder of HeritageObjects
* be documented by DigitalAssets (portraits, letters, biographies, articles)
 
Roles belong to relationships, not to the Person entity itself.


----
Purpose: Persons model historical agency, responsibility, and participation.
 
Implementation:
- automatic numbering of Person entities realized with custom module: PE-00123
- use for plain text for birthday and deathday due to drupal limitation in Date & Time widget
- use of custom module to verify the day format DD/MM/YYYY
- both modules are implemented in heritage-tweaks
- first view operational
ToDo: refinement
 
=== Step 6: HeritageObject implementation ===
The implementation of HeritageObject abbreviated Object in Drupal
 
A '''HeritageObject (HO)''' represents a historical, conceptual, or material entity that is the subject of study.
 
It answers the question:
 
''“What is the thing we are studying?”''
 
A HeritageObject may represent:
 
* a sanatorium
* a building
* a document or register
* a historically meaningful place
* a room, component, or architectural element
* a conceptual or functional unit (e.g. “medical practice”)
 
HeritageObjects are '''recursive'''.
 
Each HeritageObject may:
 
* have zero or one parent HeritageObject
* have zero or more child HeritageObjects
 
A HeritageObject may:
 
* be documented by multiple DigitalAssets
* designate one DigitalAsset as preferred representation
* be linked to Persons with roles
* be linked to Organizations with roles
* have Persons or Organizations as holders
* belong to multiple ResearchChapters
* be tagged with Keywords
* be associated with one or more Places
 
Purpose: HeritageObjects are the primary conceptual anchors of the research.
 
Implementation:
- automatic numbering of object entity: OB-00123
- Onject is recursive
 
ToDo
- implementation of a many to many relationship between Object and Asset
- One digital Asset is a prefered Asset only for illustration purposes of the Object in a view
- Notion of top" Asset in the asset structure is the Asset without parent to by used in the many-to-many relationship. This top asset gives also access to the full tree of assets linked to that top. That top may change in the lifetime of the asset-tree (decided by the user).


=== Step 5: Object & Advanced Relationships (Deferred) ===
=== Step 7: Object & Advanced Relationships ===
Type:
Type:
* Custom Content Entities
* Custom Content Entities
* Role-based relationships
* Role-based relationships
 
* other many-to-many relationships
This step is explicitly deferred until asset logic is proven and Places is complete


----
----
Line 279: Line 360:
* table of existing records
* table of existing records
* add/edit via simple forms
* add/edit via simple forms
Status: done


For Assets:
For Assets:
Line 285: Line 368:
* guided asset discovery
* guided asset discovery
* no massive tables
* no massive tables
Status: Done,
Refining realised dealing with massive amounts of assets: using a combined field filter.


----
----
Line 297: Line 383:
Mechanisms:
Mechanisms:
* field descriptions
* field descriptions
* ℹ️ icons
* ℹ️ icons (difficult in Drupal - placeholders may help here)
* collapsible help sections
* collapsible help sections
 
* TBD?: link to MediaWiki Reasearch namespace for extended documentation and system philosophy desccription
No separate manuals.


----
----
Line 307: Line 392:


Automation is handled via:
Automation is handled via:
* Drupal configuration
* Drupal configuration and extra available modules
* ECA workflows
* Custom modules if really necessary, and simplifying a lot the implementation
* Custom event subscribers if required
* take care: using drupal 11.3 - based on new (OO) concepts - needs special attention in building custom modules


Automation is used to:
Automation is used to:
Line 339: Line 424:


AI output must conform to this blueprint.
AI output must conform to this blueprint.
== AI Session protocol ==
* no hurry - simple step by simple step: AI proposes, sysop executes finishing with ACK
* no long explanations and justifications - sysop will ask for if needed.
* making the requirement work is the most important step, sysop will documenent once a milestone is achieved.
* AI will suggest a synthesis in mediawikitext format on sysop request to feed the documentation


----
----
Line 360: Line 451:
Decisions:  
Decisions:  
* GIN skin is used for administration and user input in mandatory DARK mode.
* GIN skin is used for administration and user input in mandatory DARK mode.
] SOLO skin is used for public pages.
* SOLO skin is used for public pages.


----
----
Line 374: Line 465:
==== Mandatory Requirements ====
==== Mandatory Requirements ====
* '''Permanent dark mode''' is used via the GIN skin/template
* '''Permanent dark mode''' is used via the GIN skin/template
* No custom CSS or hacks
* Preferred no custom CSS or hacks  


==== Scope ====
==== Scope ====
Line 390: Line 481:
** low-contrast-stress
** low-contrast-stress
** uncluttered
** uncluttered
* No experimental or unstable admin themes are permitted


----
----
Line 437: Line 527:
field "Description" - ch_description -- field_ch_description
field "Description" - ch_description -- field_ch_description


== Implementation Status - March 5th 2026) ==
Due to limitation in Drupal concerning the Data and Time widget, a plain text field is used for "day"..
A custom module checks the format DD/MM/YYY and the field is limited to 10 chars, explanation about the format including also a placemarker with the format. The machine field name should end on "_day".
 
== Implementation Status - March 23th 2026) ==


Entities implemented:
Entities implemented:
Line 445: Line 538:
* Organisation
* Organisation
* Asset (basic structure)
* Asset (basic structure)
* Person
* Object


All entities include:
All entities include:
Line 450: Line 546:
* edit workflow via dashboard
* edit workflow via dashboard
* recursive relationships where required
* recursive relationships where required
* FK implemented where required
* FK implemented  
* entity references verified
* entity references verified


Automation for DigitalAsset identifiers is not yet implemented.
== End of Blueprint ==
 
 
== Appendix - 1:  Data Model -


== End of Blueprint ==


== appendix:  Data Model - Core Mermaid verion 4.4 ==
The version 4.4 has been adapted to Drupal naming used or planned to use.
<pre>
<pre>
// =====================================================
// Costasano Heritage Database Model — v5.0
// =====================================================
// ==== HERITAGE OBJECTS ====
Table Object {
  Code string [pk]
  Parent string [ref: > Object.Code]
  Name string
  Type string
  Subtype string
  Place string [ref: > Place.Code]
  DateFrom date
  DateTo date
  Description text
  Notes text
}
// ==== DIGITAL ASSETS ====
Table Asset {
  Caption string
  Code string [pk]
  Chapter string [ref: > Chapter.Code]
  Place string [ref: > Place.Code]
  Organisation string [ref: > Organisation.Code]
  Sequence int
  MediaFile string [ref: > Files.id]
  Parent string [ref: > Asset.Code]
  AssetSourceType string [ref: > AssetSourceType.Code]
  AssetType string [ref: > AssetType.Code]
  SourceReference string
  Description text
  Notes text
  AiProcessed boolean
  Citation text
  Permalink string
  Repository string
  Rights string
  IsPublishable boolean
}
// ==== EXTERNAL DRUPAL FILES ====


erDiagram
Table Files {
    OBJECT ||--o{ ASSET : "through ObjectAsset"
  id string [pk]
    OBJECT ||--o{ PERSON : "through ObjectPerson"
  Label string
    OBJECT ||--o{ ORGANISATION : "through ObjectOrganisation"
  Timestamp datetime
    OBJECT ||--o{ CHAPTER : "through ObjectChapter"
  User string
    OBJECT ||--o{ KEYWORDS : "through ObjectKeyword"
  Comment text
    OBJECT ||--o{ PERSON : "through ObjectHolder"
  Size int
    OBJECT ||--o{ ORGANISATION : "through ObjectHolder"
  Sha1 string
    OBJECT }o--|| PLACE : "located in"
  Mime string
    OBJECT }o--|| OBJECT : "has parent"
  Url string
   
}
    ASSET ||--o{ PERSON : "through PersonAsset"
    ASSET ||--o{ ORGANISATION : "through OrganisationAsset"
    ASSET }o--|| CHAPTER : "in chapter"
    ASSET }o--|| PLACE : "located in"
    ASSET }o--|| ORGANISATION : "from organisation"
    ASSET }o--|| FILES : "uses file"
    ASSET }o--|| ASSETSOURCETYPE : "has source type"
    ASSET }o--|| ASSETTYPE : "has asset type"
    ASSET }o--|| ASSET : "has parent"
   
    PERSON ||--o{ ORGANISATION : "through PersonOrganisationRole"
    PERSON }o--|| PLACE : "from place"
    PERSON }o--|| ORGANISATION : "through ObjectHolder"
    PERSON }o--|| OBJECT : "through ObjectHolder"
   
    ORGANISATION }o--|| PLACE : "located in"
   
    PLACE }o--|| PLACE : "has parent"
   
    CHAPTER }o--|| CHAPTER : "has parent"
   
    FILES {
        string id PK
        string Label
        datetime Timestamp
        string User
        text Comment
        int Size
        string Sha1
        string Mime
        string Url
    }
   
    OBJECT {
        string Code PK
        string Parent FK
        string Name
        string Type
        string Subtype
        string Place FK
        date DateFrom
        date DateTo
        text Description
        text Notes
    }
   
    ASSET {
        string Code PK
        string Chapter FK
        string Place FK
        string Organisation FK
        int Sequence
        string MediaFile FK
        string Parent FK
        string AssetSourceType FK
        string AssetType FK
        string SourceReference
        text Description
        text Notes
        boolean AiProcessed
        text Citation
        string Permalink
        string Repository
        string Rights
        boolean IsPublishable
    }
   
    PERSON {
        string Code PK
        string FirstName
        string LastName
        date BirthDate
        date DeathDate
        text Biography
        text Contact
        text Notes
    }
   
    ORGANISATION {
        string Code PK
        string Name
        string Place FK
        text Contact
        text Description
        text Notes
    }
   
    PLACE {
        string Code PK
        string Parent FK
        string Name
        string Type
        float Latitude
        float Longitude
        text Description
        text Notes
    }
   
    CHAPTER {
        string Code PK
        string Name
        string Parent FK
        integer StartYear
        integer EndYear
        text Description
        text Notes
    }
   
</pre>


= Lessons learned on feb 27 2026 =
// ==== RESEARCH ENTITIES ====


This session ended in with Drupal in an undetermined stated due to a misunderstanding about the requirements, and then finally a problem wrongly using a Drupal reserved word DASHBOARD.
Table Person {
  Code string [pk]
  FirstName string
  LastName string
  BirthDate date
  DeathDate date
  Biography text
  Contact text
  Notes text
}


Restart from scratch after that day, restoring of the full virtual disks for both machines dated 26 feb.
Table Organisation {
  Code string [pk]
  Name string
  Place string [ref: > Place.Code]
  Description text
  Contact text
  Notes text
}


Conclusion of the day were chatgpt promises for restarting.
Table Place {
  Code string [pk]
  Parent string [ref: > Place.Code]
  Label string
  Type string
  Latitude float
  Longitude float
  Description text
  Notes text
}


Tomorrow I will:
Table Chapter {
  Code string [pk]
  Description string
  Parent string [ref: > Chapter.Code]
  StartYear integer
  EndYear integer
  Notes text
}


* avoid cleverness
// ==== LOOKUP TABLES ====
* avoid custom routing early
* avoid reserved names
* rely on Drupal defaults first
* reduce bash steps to the minimum stop earlier when entropy appears


Agreement: You bring architectural clarity. I bring Drupal-specific caution. That’s a workable division.
Table ObjectType {
  Code string [pk]
  Description text
}


== Important AI protocal ==
Table AssetSourceType {
After the agreement an a workflow, we work step by step, no hurry. AI proposes a step, I execute and report back the result and then only we go for the next step. Too much explanation is NOT needed, as I am a novice in this field. After 50+ years in ICT, I understand mostly what the steps do and if not, I will ask for. This should permit for a slow but steady flow towards the endgoal of the session.
  Code string [pk]
  Label string
  Description text
}


= Modules already enabled in our Drupal 11 configuration ==
Table AssetType {
  Code string [pk]
  Name string
  Description text
}
 
Table AssetRole {
  Code string [pk]
  Name string
  Description text
}
 
Table PersonRole {
  Code string [pk]
  Name string
  Description text
}
 
Table OrganisationRole {
  Code string [pk]
  Name string
  Description text
}
 
Table Keywords {
  Code string [pk]
  Name string
  Description text
}
 
// ==== RELATIONSHIP TABLES (Junctions) ====
 
Table ObjectAsset {
  id string [pk]
  Object string [ref: > Object.Code]
  Asset string [ref: > Asset.Code]
  Role string [ref: > AssetRole.Code]
  IsPreferred boolean
}
 
Table PersonAsset {
  id string [pk]
  Person string [ref: > Person.Code]
  Asset string [ref: > Asset.Code]
}
 
Table OrganisationAsset {
  id string [pk]
  Organisation string [ref: > Organisation.Code]
  Asset string [ref: > Asset.Code]
}
 
Table OjectChapter {
  id string [pk]
  Object string [ref: > Object.Code]
  Chapter string [ref: > Chapter.Code]
}
 
Table ObjectPerson {
  id string [pk]
  Object string [ref: > Object.Code]
  Person string [ref: > Person.Code]
  Role string [ref: > PersonRole.Code]
}
 
Table ObjectOrganisation {
  id string [pk]
  Object string [ref: > Object.Code]
  Organisation string [ref: > Organisation.Code]
  Role string [ref: > OrganisationRole.Code]
}
 
Table PersonOrganisationRole {
  id string [pk]
  Person string [ref: > Person.Code]
  Organisation string [ref: > Organisation.Code]
  Role string [ref: > OrganisationRole.Code]
}
 
Table ObjectKeyword {
  id string [pk]
  Object string [ref: > Object.Code]
  Keyword string [ref: > Keywords.Code]
}
 
Table ObjectHolder {
  id string [pk]
  Object string [ref: > Object.Code]
  Person string [ref: > Person.Code]
  Organisation string [ref: > Organisation.Code]
}
</pre>
 
= Appendix - 2: Modules already enabled in our Drupal 11 configuration - version 20260319 ==


<pre>
<pre>
mngr@localhost:/var/www/drupal$ drush pm:list --status=enabled
mngr@localhost:/var/www/drupal$ drush pm:list --status=enabled
---------------- ------------------------------------- --------- ----------  
  ---------------- ----------------------------------------------------------------------- --------- ----------
  Package          Name                                  Status    Version 
  Package          Name                                                                    Status    Version 
---------------- ------------------------------------- --------- ----------  
---------------- ----------------------------------------------------------------------- --------- ----------  
   Core            Announcements (announcements_feed)    Enabled  11.3.3   
   Core            Announcements (announcements_feed)                                     Enabled  11.3.5    
  Core            Automated Cron (automated_cron)      Enabled  11.3.3   
   Core            Automated Cron (automated_cron)                                         Enabled  11.3.5    
  Core            BigPipe (big_pipe)                   Enabled  11.3.3    
   Core            BigPipe (big_pipe)                                                     Enabled  11.3.5    
   Core            Block (block)                         Enabled  11.3.3    
   Core            Block (block)                                                           Enabled  11.3.5    
   Core            Block Content (block_content)         Enabled  11.3.3    
   Core            Block Content (block_content)                                           Enabled  11.3.5    
   Core            Breakpoint (breakpoint)               Enabled  11.3.3    
   Core            Breakpoint (breakpoint)                                                 Enabled  11.3.5    
   Core            CKEditor 5 (ckeditor5)               Enabled  11.3.3    
   Core            CKEditor 5 (ckeditor5)                                                 Enabled  11.3.5    
   Core            Comment (comment)                     Enabled  11.3.3    
   Core            Comment (comment)                                                       Enabled  11.3.5    
   Core            Configuration Manager (config)       Enabled  11.3.3    
   Core            Configuration Manager (config)                                         Enabled  11.3.5    
   Core            Contact (contact)                     Enabled  11.3.3    
   Core            Contact (contact)                                                       Enabled  11.3.5    
   Core            Contextual Links (contextual)         Enabled  11.3.3    
   Core            Contextual Links (contextual)                                           Enabled  11.3.5    
   Field types      Datetime (datetime)                   Enabled  11.3.3    
   Field types      Datetime (datetime)                                                     Enabled  11.3.5    
   Field types      Datetime Range (datetime_range)       Enabled  11.3.3    
   Field types      Datetime Range (datetime_range)                                        Enabled  11.3.5    
   Core            Database Logging (dblog)             Enabled  11.3.3    
   Core            Database Logging (dblog)                                               Enabled  11.3.5    
   Core            Internal Dynamic Page Cache          Enabled  11.3.3    
   Core            Internal Dynamic Page Cache (dynamic_page_cache)                       Enabled  11.3.5    
                  (dynamic_page_cache)                                     
   Core            Text Editor (editor)                                                   Enabled  11.3.5    
   Core            Text Editor (editor)                 Enabled  11.3.3    
   Core            Field (field)                                                           Enabled  11.3.5    
   Core            Field (field)                         Enabled  11.3.3    
   Core            Field UI (field_ui)                                                     Enabled  11.3.5    
   Core            Field UI (field_ui)                   Enabled  11.3.3    
   Field types      File (file)                                                             Enabled  11.3.5    
   Field types      File (file)                           Enabled  11.3.3    
   Core            Filter (filter)                                                         Enabled  11.3.5    
   Core            Filter (filter)                       Enabled  11.3.3    
   Core            Help (help)                                                             Enabled  11.3.5    
   Core            Help (help)                           Enabled  11.3.3    
   Core            History (history)                                                      Enabled  11.3.5    
   Core            History (history)                     Enabled  11.3.3    
  Field types      Image (image)                                                           Enabled  11.3.5   
   Field types      Image (image)                         Enabled  11.3.3    
   Core            Inline Form Errors (inline_form_errors)                                 Enabled  11.3.5    
   Core            Inline Form Errors                    Enabled  11.3.3    
   Core            Layout Builder (layout_builder)                                         Enabled  11.3.5   
                  (inline_form_errors)                                    
  Core            Layout Discovery (layout_discovery)                                    Enabled  11.3.5    
   Core            Layout Builder (layout_builder)       Enabled  11.3.3    
   Field types      Link (link)                                                             Enabled  11.3.5    
   Core            Layout Discovery (layout_discovery)   Enabled  11.3.3    
   Core            Media (media)                                                           Enabled  11.3.5    
   Field types      Link (link)                           Enabled  11.3.3    
   Core            Media Library (media_library)                                           Enabled  11.3.5    
   Core            Media (media)                         Enabled  11.3.3    
   Core            Custom Menu Links (menu_link_content)                                  Enabled  11.3.5    
   Core            Media Library (media_library)         Enabled  11.3.3    
   Core            Menu UI (menu_ui)                                                       Enabled  11.3.5    
   Core            Custom Menu Links                     Enabled  11.3.3    
   Core            MySQL (mysql)                                                           Enabled  11.3.5    
                  (menu_link_content)                                     
   Core            Node (node)                                                             Enabled  11.3.5    
   Core            Menu UI (menu_ui)                     Enabled  11.3.3    
   Field types      Options (options)                                                       Enabled  11.3.5    
   Core            MySQL (mysql)                         Enabled  11.3.3    
   Core            Internal Page Cache (page_cache)                                       Enabled  11.3.5    
   Core            Node (node)                           Enabled  11.3.3    
   Core            Path (path)                                                             Enabled  11.3.5    
   Field types      Options (options)                     Enabled  11.3.3    
   Core            Path alias (path_alias)                                                 Enabled  11.3.5    
   Core            Internal Page Cache (page_cache)     Enabled  11.3.3    
   Core            Responsive Image (responsive_image)                                     Enabled  11.3.5    
   Core            Path (path)                           Enabled  11.3.3    
   Core            Search (search)                                                         Enabled  11.3.5    
   Core            Path alias (path_alias)               Enabled  11.3.3    
   Core            Shortcut (shortcut)                                                     Enabled  11.3.5    
   Core            Responsive Image (responsive_image)   Enabled  11.3.3    
   Core            System (system)                                                         Enabled  11.3.5    
   Core            Search (search)                       Enabled  11.3.3    
   Core            Taxonomy (taxonomy)                                                     Enabled  11.3.5    
   Core            Shortcut (shortcut)                   Enabled  11.3.3    
   Field types      Text (text)                                                             Enabled  11.3.5    
   Core            System (system)                       Enabled  11.3.3    
   Core            Toolbar (toolbar)                                                       Enabled  11.3.5    
   Core            Taxonomy (taxonomy)                   Enabled  11.3.3    
   Core            Update Status (update)                                                 Enabled  11.3.5    
   Field types      Text (text)                           Enabled  11.3.3    
   Core            User (user)                                                             Enabled  11.3.5    
   Core            Toolbar (toolbar)                     Enabled  11.3.3    
   Core            Views (views)                                                           Enabled  11.3.5    
   Core            Update Status (update)               Enabled  11.3.3    
   Core            Views UI (views_ui)                                                     Enabled  11.3.5    
   Core            User (user)                           Enabled  11.3.3    
   Core            Workspaces (workspaces)                                                 Enabled  11.3.5    
   Core            Views (views)                         Enabled  11.3.3    
   Core            Workspaces UI (workspaces_ui)                                           Enabled  11.3.5    
   Core            Views UI (views_ui)                   Enabled  11.3.3    
   Field types      Address (address)                                                       Enabled  2.0.4     
   Core            Workspaces (workspaces)               Enabled  11.3.3    
  Development      Asset Injector (asset_injector)                                        Enabled  8.x-2.21 
   Core            Workspaces UI (workspaces_ui)         Enabled  11.3.3    
   Field types      Color Field (color_field)                                               Enabled  3.0.2     
   Field types      Address (address)                     Enabled  2.0.4     
   Other            Computed Field (computed_field)                                        Enabled  4.0.0      
   Field types      Color Field (color_field)             Enabled  3.0.2     
  Other            Contact Formatter (contact_formatter)                                   Enabled  2.0.4   
   Other            Contact Formatter                    Enabled  2.0.4      
   Core            Dashboard (dashboard)                                                   Enabled  2.2.0     
                  (contact_formatter)                                      
   Field types      Entity Reference Revisions (entity_reference_revisions)                Enabled  8.x-1.14   
   Core            Dashboard (dashboard)                 Enabled  2.2.0     
   Fields          Field Group (field_group)                                               Enabled  4.0.0     
   Field types      Entity Reference Revisions           Enabled  8.x-1.14   
   File metadata    File metadata manager (file_mdm)                                       Enabled  3.2.0     
                  (entity_reference_revisions)                             
   File metadata    File metadata - EXIF (file_mdm_exif)                                    Enabled  3.2.0     
   Fields          Field Group (field_group)             Enabled  4.0.0     
   File metadata    File metadata - Font (file_mdm_font)                                    Enabled  3.2.0     
   File metadata    File metadata manager (file_mdm)     Enabled  3.2.0     
   Geocoding        Geocoder (geocoder)                                                     Enabled  8.x-4.31  
   File metadata    File metadata - EXIF                 Enabled  3.2.0     
   Geocoding        Geocoder Address (geocoder_address)                                     Enabled  8.x-4.31  
                  (file_mdm_exif)                                         
   Geocoding        Geocoder Field (geocoder_field)                                         Enabled  8.x-4.31  
   File metadata    File metadata - Font                 Enabled  3.2.0     
   Geocoding        Geocoder Geofield (geocoder_geofield)                                  Enabled  8.x-4.31  
                  (file_mdm_font)                                         
  Geofield        Geofield (geofield)                                                     Enabled  10.3.4    
   Geocoding        Geocoder (geocoder)                   Enabled  8.x-4.30  
   Geolocation      Geolocation (geolocation)                                               Enabled  8.x-3.14 
   Geocoding        Geocoder Address (geocoder_address)   Enabled  8.x-4.30  
   Geolocation      Geolocation - Address (geolocation_address)                             Enabled  8.x-3.14 
   Geocoding        Geocoder Field (geocoder_field)       Enabled  8.x-4.30  
   Geolocation      Geolocation - Baidu Maps (geolocation_baidu)                            Enabled  8.x-3.14 
   Geocoding        Geocoder Geofield                     Enabled  8.x-4.30  
   Geolocation      Geolocation - Here Maps (geolocation_here)                             Enabled  8.x-3.14 
                  (geocoder_geofield)                                     
   Geolocation      Geolocation - Leaflet (geolocation_leaflet)                            Enabled  8.x-3.14 
  Geofield        Geofield (geofield)                   Enabled  10.3.3    
  Other            Gin Toolbar (gin_toolbar)                                               Enabled  3.0.3   
   Other            Gin Toolbar (gin_toolbar)             Enabled  3.0.3   
   Media            Image Effects (image_effects)                                           Enabled  5.0.0   
   Media            Image Effects (image_effects)         Enabled  5.0.0   
   Media            ImageMagick (imagemagick)                                               Enabled  5.0.1   
   User interface  Klaro Cookie & Consent Manager        Enabled  3.0.8   
   jQuery UI        jQuery UI (jquery_ui)                                                  Enabled  8.x-1.
                  (klaro)                                                 
  jQuery UI        jQuery UI Autocomplete (jquery_ui_autocomplete)                         Enabled  2.1.0   
   Geofield        Leaflet (leaflet)                     Enabled  10.4.4   
   jQuery UI        jQuery UI Menu (jquery_ui_menu)                                         Enabled  2.1.0   
   Geofield        Leaflet Markercluster                Enabled  10.4.4   
   User interface  Klaro Cookie & Consent Manager (klaro)                                  Enabled  3.0.8   
                  (leaflet_markercluster)                                  
  Geofield        Leaflet (leaflet)                                                       Enabled   10.4.4    
   Geofield        Leaflet Views (leaflet_views)         Enabled  10.4.4   
  Geofield        Leaflet Markercluster (leaflet_markercluster)                           Enabled  10.4.4   
   User interface  Linkit (linkit)                       Enabled  7.0.13   
   Geofield        Leaflet Views (leaflet_views)                                          Enabled  10.4.4    
   Paragraphs      Paragraphs Type Permissions          Enabled  8.x-1.20 
  User interface  Linkit (linkit)                                                         Enabled   7.0.13    
                  (paragraphs_type_permissions)                            
  Other            Media Library Form Element (media_library_form_element)                 Enabled  2.1.4   
   Paragraphs      Paragraphs (paragraphs)               Enabled  8.x-1.20 
   Paragraphs      Paragraphs Type Permissions (paragraphs_type_permissions)               Enabled  8.x-1.20 
   Paragraphs      Paragraph Bundle 3D Carousel          Enabled  1.0.15   
   Paragraphs      Paragraphs (paragraphs)                                                Enabled  8.x-1.20 
                  (paragraph_bundle_3d_carousel)                          
   Paragraphs      Paragraph Bundle 3D Carousel (paragraph_bundle_3d_carousel)             Enabled  1.0.16    
   Paragraphs      Paragraph Bundle 3D Flip Box          Enabled  1.0.15    
   Paragraphs      Paragraph Bundle 3D Flip Box (paragraph_bundle_3d_flip_box)            Enabled  1.0.16    
                  (paragraph_bundle_3d_flip_box)                          
   Paragraphs      Paragraph Bundle Accordion (paragraph_bundle_accordion)                Enabled  1.0.16    
   Paragraphs      Paragraph Bundle Accordion            Enabled  1.0.15    
   Paragraphs      Paragraph Bundle Alert (paragraph_bundle_alert)                        Enabled  1.0.16    
                  (paragraph_bundle_accordion)                            
   Paragraphs      Paragraph Bundle Block (paragraph_bundle_block)                        Enabled  1.0.16    
   Paragraphs      Paragraph Bundle Alert                Enabled  1.0.15    
   Paragraphs      Paragraph Bundle Block Content (paragraph_bundle_block_content)        Enabled   1.0.16    
                  (paragraph_bundle_alert)                                
   Paragraphs      Paragraph Bundle Card (paragraph_bundle_card)                          Enabled  1.0.16    
   Paragraphs      Paragraph Bundle Block                Enabled  1.0.15   
   Paragraphs      Paragraph Bundle Carousel (paragraph_bundle_carousel)                  Enabled  1.0.16    
                  (paragraph_bundle_block)                                
  Paragraphs      Paragraph Bundle Contact Form (paragraph_bundle_contact_form)          Enabled  1.0.16    
  Paragraphs      Paragraph Bundle Block Content        Enabled  1.0.15   
   Paragraphs      Paragraph Bundle Content (paragraph_bundle_content)                    Enabled  1.0.16    
                  (paragraph_bundle_block_content)                         
   Paragraphs      Paragraph Bundle Grid (paragraph_bundle_grid)                          Enabled  1.0.16    
   Paragraphs      Paragraph Bundle Card                Enabled  1.0.15   
   Paragraphs      Paragraph Bundle Hero (paragraph_bundle_hero)                          Enabled  1.0.16    
                  (paragraph_bundle_card)                                 
  Paragraphs       Paragraph Bundle Icon (paragraph_bundle_icon)                          Enabled  1.0.16    
   Paragraphs      Paragraph Bundle Carousel            Enabled  1.0.15    
   Paragraphs      Paragraph Bundle Image (paragraph_bundle_image)                        Enabled  1.0.16    
                  (paragraph_bundle_carousel)                             
   Paragraphs      Paragraph Bundle Image Background (paragraph_bundle_image_background)  Enabled  1.0.16    
   Paragraphs      Paragraph Bundle Contact Form        Enabled  1.0.15    
   Paragraphs      Paragraph Bundle Image Grid (Image Gallery - Lightbox)                  Enabled  1.0.16    
                  (paragraph_bundle_contact_form)                         
                   (paragraph_bundle_image_grid)                                                              
   Paragraphs      Paragraph Bundle Content              Enabled  1.0.15    
   Paragraphs      Paragraph Bundle Image Overlay (paragraph_bundle_image_overlay)        Enabled  1.0.16    
                  (paragraph_bundle_content)                               
   Paragraphs       Paragraph Bundle Layout (paragraph_bundle_layout)                       Enabled  1.0.16   
   Paragraphs      Paragraph Bundle Grid                Enabled  1.0.15    
   Paragraphs      Paragraph Bundle Modal (paragraph_bundle_modal)                        Enabled  1.0.16   
                  (paragraph_bundle_grid)                                 
  Paragraphs      Paragraph Bundle Node Reference (paragraph_bundle_node_reference)       Enabled   1.0.16   
   Paragraphs      Paragraph Bundle Hero                Enabled  1.0.15    
   Paragraphs      Paragraph Bundle Parallax (paragraph_bundle_parallax)                   Enabled  1.0.16    
                  (paragraph_bundle_hero)                                 
   Paragraphs      Paragraph Bundle Slideshow (paragraph_bundle_slideshow)                 Enabled  1.0.16    
   Paragraphs      Paragraph Bundle Icon                Enabled   1.0.15    
  Paragraphs      Paragraph Bundle Tabs (paragraph_bundle_tabs)                           Enabled  1.0.16    
                  (paragraph_bundle_icon)                                 
   Paragraphs      Paragraphs Bundles (paragraphs_bundles)                                 Enabled  1.0.16    
   Paragraphs      Paragraph Bundle Image                Enabled  1.0.15    
  Mail            SMTP Authentication Support (smtp)                                      Enabled  8.x-1.4 
                  (paragraph_bundle_image)                                 
  Solo Suite      Solo Utilities (solo_utilities)                                        Enabled  1.0.6   
   Paragraphs      Paragraph Bundle Image Background    Enabled  1.0.15    
  Other            Sophron (sophron)                                                      Enabled  3.1.0   
                  (paragraph_bundle_image_background)                     
  Media            SVG Image Responsive (svg_image_responsive)                            Enabled  3.2.2   
  Paragraphs      Paragraph Bundle Image Grid (Image    Enabled  1.0.15    
  Media            SVG image (svg_image)                                                  Enabled  3.2.2   
                  Gallery - Lightbox)                                     
  Costasano        Costasano Asset (costasano_asset)                                      Enabled           
                  (paragraph_bundle_image_grid)                           
  Heritage        Heritage Codes (heritage_codes)                                        Enabled  1.0.0   
   Paragraphs      Paragraph Bundle Image Overlay        Enabled  1.0.15    
  Heritage        Heritage Tweaks (heritage_tweaks)                                      Enabled           
                  (paragraph_bundle_image_overlay)                         
  Core            Claro (claro)                                                          Enabled  11.3.5   
   Paragraphs      Paragraph Bundle Layout              Enabled  1.0.15    
  Core            Olivero (olivero)                                                      Enabled  11.3.5   
                  (paragraph_bundle_layout)                               
                  Gin (gin)                                                              Enabled  5.0.12   
   Paragraphs      Paragraph Bundle Modal                Enabled  1.0.15    
  Solo            Solo (solo)                                                            Enabled  1.0.31   
                  (paragraph_bundle_modal)                                 
---------------- ----------------------------------------------------------------------- --------- ----------
  Paragraphs       Paragraph Bundle Node Reference      Enabled  1.0.15    
                  (paragraph_bundle_node_reference)                       
   Paragraphs      Paragraph Bundle Parallax            Enabled  1.0.15    
                  (paragraph_bundle_parallax)                             
   Paragraphs      Paragraph Bundle Slideshow            Enabled  1.0.15    
                  (paragraph_bundle_slideshow)                             
   Paragraphs      Paragraph Bundle Tabs                Enabled  1.0.15    
                   (paragraph_bundle_tabs)                                  
   Paragraphs      Paragraphs Bundles                    Enabled  1.0.15    
                  (paragraphs_bundles)                                     
   Solo Suite       Solo Utilities (solo_utilities)       Enabled  1.0.6   
   Media            SVG Image Responsive                  Enabled  3.2.2   
                  (svg_image_responsive)                                  
   Media            SVG image (svg_image)                Enabled  3.2.2   
   Core            Claro (claro)                         Enabled  11.3.3    
   Core            Olivero (olivero)                     Enabled  11.3.3    
                  Gin (gin)                             Enabled  5.0.12    
   Solo            Solo (solo)                           Enabled  1.0.30    
 
</pre>
</pre>

Latest revision as of 10:51, 23 March 2026

Costasano Heritage Project — Drupal 11 Architecture & Workflow Blueprint (v6.5)

Purpose of this Document

This page defines the architectural, conceptual, and workflow foundations of the Costasano Heritage Project.

It serves as:

  • a stable reference for human contributors
  • a briefing document for AI-assisted work sessions
  • a safeguard against context loss over long-term development

All future design, implementation, and automation decisions must be compatible with the principles defined here.


Project Overview

The Costasano Heritage Project is a long-term digital heritage initiative operated by members of the Costa Sano Club (70+ years old, amateur historians, non-ICT specialists, except for Martin, realising the IT-project, also amateur historian).

The project manages:

  • hundreds of gigabytes of documents, images, and maps
  • collaborative historical research
  • multi-channel dissemination (wiki, public website, exhibitions, video)

The system is designed for decades-long durability, not short-term publication.


Core Philosophy

Authoritative Source Principle

There is exactly ONE authoritative system for data and assets:

  • Drupal 11.3

All other outputs (MediaWiki, public website, video, exhibitions) are derivatives.

No downstream system is allowed to correct, invent, or override facts. All corrections must return to Drupal.


Asset-Centric Design

The central object of the entire system is:

Asset + File (ONE asset = ONE file)

Everything else (chapter, place, organisation) exists to:

  • contextualize assets
  • classify assets
  • generate stable identifiers
  • reuse assets across outputs
  • chapters provide a sort of timeline

Ingest First, Enrich Later

The system must allow:

  • rapid bulk ingestion of files with minimal metadata
  • gradual collaborative enrichment over time
  • clear lifecycle states without pressure for completeness

Completeness is a process, not a prerequisite.


Target Users & UX Constraints

User Profile

  • Age: 70+
  • Background: amateur historians
  • ICT skills: minimal
  • Tolerance for complexity: low

UX Non-Negotiables

  • No technical terminology exposed (no “entity”, “taxonomy”, “foreign key”)
  • No cluttered forms
  • Dashboard-first and only navigation
  • Large click targets
  • Predictable layouts
  • Dark mode mandatory (accessibility)

Users must never feel they are “using Drupal”.


System Architecture

Infrastructure

  • Reverse Proxy: Windows Server 2019 (IIS + ARR, SSL offloading)
  • Web Server: AlmaLinux 10.1 (Apache 2.4.63, PHP 8.3.29, PHP-FPM)
  • Database Server: AlmaLinux 10.1 (MariaDB 10.11.15)
  • Drupal 11.3.5
  • SELinux: Enforcing
  • PHP-FPM: Per-site pools
  • Filesystem: Hardened

Operational Constants


Output Channels

1. MediaWiki (Research & Writing)

Role:

  • illustrated research pages
  • collaborative narrative writing
  • preparation for Wikipedia publication

MediaWiki does NOT:

  • store authoritative metadata
  • manage files
  • generate identifiers

2. Public Drupal Website

Role:

  • curated presentation of selected research
  • timelines, maps, galleries

Only “complete” or approved assets are shown publicly.


3. Offline Outputs

  • video documentaries
  • lectures
  • exhibitions

These reuse:

  • the same assets
  • the same identifiers
  • the same metadata

Authority Entity Implementation Strategy

Authority entities are implemented progressively, from simplest to most complex.


Step 1: Chapter (Temporal Authority)

Type:

  • Drupal Custom Content Entity (authority)

Meaning:

  • historical periods / timeline segmentation
  • not editorial or narrative content

Characteristics:

  • stable Code (max 6 characters) like CHxx.ab CH01, CH01a, CH01aa, CH01ab
  • recursive (parent/child) two levels using small letters after the first four
  • stable Code (max 6 characters)
  • used as first mandatory component in asset identifiers
  • no sequence field

Dashboard pattern:

  • table of existing records
  • add new record
  • click pencil in front of row to edit

Status: Drupal Context Type and Dashboard page operational Changed decision about chapter code layout ToDo (max 6 characters)

  • Address field for geocoding
  • coordinates auto-derived when possible
  • coordinates never required for ingestion

Purpose:

  • spatial context
  • optionally reused across assets for numbering reasoons
  • reused for organisations

Status: Drupal Context Type and Dashboard page operational Recently added: type list, geo link in view towards openstreetmap Added view adapted to type. Address to coordinates implemented using Openstreatmap providers. ToDo:Completing helpfunctions


Step 3: Organisation (Institutional Authority)

Type:

  • Drupal Custom Content Entity (authority)

Characteristics:

  • stable Code (max 6 characters)
  • linked to a Place
  • optionally reused across assets for numbering

Purpose:

  • institutional context
  • archival provenance

Status: Drupal Context Type and Dashboard page operational ToDo: adding map view based on Place coordinnates now that provider is available Completing help functions


Step 4: Asset (CORE ENTITY)

Type:

  • Drupal Custom Content Entity

Rules:

  • ONE asset = ONE file
  • file is immutable once uploaded
  • identifier is immutable once generated
  • physical filenames are managed by Drupal
  • original filename is preserved for user reference

Identifier format:

  • Chapter.Code
  • Context.Code = Place.Code OR Organisation.Code
  • Scoped 5-digit counter (asset sequence only)

Example:

CH03ab-OOSTEN-00007

Asset creation is impossible before Chapter, Place, and Organisation exist.

Status: Drupal Context Type and View complete Use of special configuration of classic Media-Library for media upload. Upload of images, documents, video and audio foreseen Automatic numbering for asset via a custom module Creation in 2 steps: first essential fields to generate autonumbering. After that, use of editing via table to fill un further fields like description and note. Optional change of other fields except autocode. View enhanced with search filter. ToDo: complete help functions Remark: Inital configuration with Code as PK (Drupal Title) has been abandoned. Now Code is a classic field and the Title field is a Caption field. This is a short description of the file.

Next Major step: Person and HeritageObject and the m-m relationship with Asset

Step 5: Person implementation

A Person represents a historical individual with agency.

It answers the question:

“Who was involved historically?”

A person is:

  • religious sisters
  • directors
  • architects
  • patients
  • shareholders
  • board members

A Person may:

  • play roles in relation to HeritageObjects
  • play roles within Organizations
  • act as a holder of HeritageObjects
  • be documented by DigitalAssets (portraits, letters, biographies, articles)

Roles belong to relationships, not to the Person entity itself.

Purpose: Persons model historical agency, responsibility, and participation.

Implementation: - automatic numbering of Person entities realized with custom module: PE-00123 - use for plain text for birthday and deathday due to drupal limitation in Date & Time widget - use of custom module to verify the day format DD/MM/YYYY - both modules are implemented in heritage-tweaks - first view operational ToDo: refinement

Step 6: HeritageObject implementation

The implementation of HeritageObject abbreviated Object in Drupal

A HeritageObject (HO) represents a historical, conceptual, or material entity that is the subject of study.

It answers the question:

“What is the thing we are studying?”

A HeritageObject may represent:

  • a sanatorium
  • a building
  • a document or register
  • a historically meaningful place
  • a room, component, or architectural element
  • a conceptual or functional unit (e.g. “medical practice”)

HeritageObjects are recursive.

Each HeritageObject may:

  • have zero or one parent HeritageObject
  • have zero or more child HeritageObjects

A HeritageObject may:

  • be documented by multiple DigitalAssets
  • designate one DigitalAsset as preferred representation
  • be linked to Persons with roles
  • be linked to Organizations with roles
  • have Persons or Organizations as holders
  • belong to multiple ResearchChapters
  • be tagged with Keywords
  • be associated with one or more Places

Purpose: HeritageObjects are the primary conceptual anchors of the research.

Implementation: - automatic numbering of object entity: OB-00123 - Onject is recursive

ToDo - implementation of a many to many relationship between Object and Asset - One digital Asset is a prefered Asset only for illustration purposes of the Object in a view - Notion of top" Asset in the asset structure is the Asset without parent to by used in the many-to-many relationship. This top asset gives also access to the full tree of assets linked to that top. That top may change in the lifetime of the asset-tree (decided by the user).

Step 7: Object & Advanced Relationships

Type:

  • Custom Content Entities
  • Role-based relationships
  • other many-to-many relationships

Asset Lifecycle & Collaboration Workflow

Roles (conceptual)

  • Ingestor
    • uploads files
    • assigns minimal context
  • Enricher
    • adds metadata
    • validates data

One person may have multiple roles.


Lifecycle States

  • Newly added
  • In progress
  • Reviewed
  • Complete

States describe maturity, not publication.


Dashboard Design Pattern

For Chapter, Place, Organisation:

  • single dashboard page
  • table of existing records
  • add/edit via simple forms

Status: done

For Assets:

  • add asset always visible
  • recent assets list
  • guided asset discovery
  • no massive tables

Status: Done, Refining realised dealing with massive amounts of assets: using a combined field filter.


Help & Guidance Strategy

Help must be:

  • contextual
  • non-intrusive
  • always available

Mechanisms:

  • field descriptions
  • ℹ️ icons (difficult in Drupal - placeholders may help here)
  • collapsible help sections
  • TBD?: link to MediaWiki Reasearch namespace for extended documentation and system philosophy desccription

Automation & Logic

Automation is handled via:

  • Drupal configuration and extra available modules
  • Custom modules if really necessary, and simplifying a lot the implementation
  • take care: using drupal 11.3 - based on new (OO) concepts - needs special attention in building custom modules

Automation is used to:

  • generate identifiers
  • manage asset counters
  • enforce immutability rules
  • reduce cognitive load

Automation must never obscure what happens.


Design Discipline Rules

  • No authority entity is implemented as editorial content
  • No field is required unless it enables a mechanism
  • No output system becomes authoritative
  • No UX decision is optimized for power users
  • Stability is more important than elegance

Usage in AI Sessions

This document must be:

  • pasted or referenced at the start of new AI-assisted sessions
  • treated as authoritative context
  • updated only when architectural decisions change and progress is made

AI output must conform to this blueprint.

AI Session protocol

  • no hurry - simple step by simple step: AI proposes, sysop executes finishing with ACK
  • no long explanations and justifications - sysop will ask for if needed.
  • making the requirement work is the most important step, sysop will documenent once a milestone is achieved.
  • AI will suggest a synthesis in mediawikitext format on sysop request to feed the documentation

Supplement — UI Theming, Accessibility & Visual Discipline

This supplement records explicit requirements related to visual theming, accessibility, and user comfort that were clarified after initial project restart. These requirements are binding and must be respected in all future design and implementation decisions.


Separation of UI Concerns

The system UI is explicitly divided into two independent domains:

  • Administrative / Dashboard UI (authenticated users)
  • Public Presentation UI (anonymous visitors)

No design, theme, or UX decision in one domain is allowed to negatively affect the other.

Decisions:

  • GIN skin is used for administration and user input in mandatory DARK mode.
  • SOLO skin is used for public pages.

Administrative & Dashboard UI (Authenticated Users)

Target Users

  • System administrator (username: mngr)
  • Club members and contributors (e.g. testuser)
  • Age profile: 70+
  • Long working sessions expected

Mandatory Requirements

  • Permanent dark mode is used via the GIN skin/template
  • Preferred no custom CSS or hacks

Scope

  • Applies to:
    • content ingestion
    • asset enrichment
    • review workflows
    • dashboards
  • Applies equally to administrators and non-technical contributors

Design Discipline

  • Accessibility and eye comfort take precedence over aesthetics
  • The administrative UI must remain:
    • predictable
    • low-contrast-stress
    • uncluttered

Public Presentation UI (Anonymous Users)

Audience

  • General public
  • Researchers
  • Visitors with unknown accessibility needs

Mandatory Requirements

  • Public-facing theme must be:
    • modern
    • responsive / adaptive
    • suitable for long-term institutional use

DECISION: SOLO skin/template has been choosen for dealing with these requirements


Timing & Implementation Rules =

  • Public-facing theming is explicitly deferred until:
    • asset logic is validated
    • authoritative entities are stable
  • Early decisions must not constrain future design exploration, but must enforce:
    • accessibility
    • adaptability
    • long-term maintainability

Stability Principle (UI) =

  • UI comfort is a prerequisite for correct decision-making
  • Visual strain increases error rates and architectural drift
  • Therefore:
    • administrative UI comfort is non-negotiable
    • public UI adaptability is mandatory

Naming conventions - Design discipline

All attributes in an entity will have the first 2 letters of the entity as prefix in the Drupal machine name. Example: Chapter field "Start Year" - machine name: ch_startyear internal storage name: field_ch_startyear field "Description" - ch_description -- field_ch_description

Due to limitation in Drupal concerning the Data and Time widget, a plain text field is used for "day".. A custom module checks the format DD/MM/YYY and the field is limited to 10 chars, explanation about the format including also a placemarker with the format. The machine field name should end on "_day".

Implementation Status - March 23th 2026)

Entities implemented:

  • Chapter
  • Place
  • Organisation
  • Asset (basic structure)
  • Person
  • Object


All entities include:

  • dashboards via Views
  • edit workflow via dashboard
  • recursive relationships where required
  • FK implemented
  • entity references verified

End of Blueprint

== Appendix - 1: Data Model -


// =====================================================
// Costasano Heritage Database Model — v5.0 
// =====================================================

// ==== HERITAGE OBJECTS ====

Table Object {
  Code string [pk]
  Parent string [ref: > Object.Code]
  Name string
  Type string
  Subtype string
  Place string [ref: > Place.Code]
  DateFrom date
  DateTo date
  Description text
  Notes text
}

// ==== DIGITAL ASSETS ====

Table Asset {
  Caption string
  Code string [pk]
  Chapter string [ref: > Chapter.Code]
  Place string [ref: > Place.Code]
  Organisation string [ref: > Organisation.Code]
  Sequence int
  MediaFile string [ref: > Files.id]
  Parent string [ref: > Asset.Code]
  AssetSourceType string [ref: > AssetSourceType.Code]
  AssetType string [ref: > AssetType.Code]
  SourceReference string
  Description text
  Notes text
  AiProcessed boolean
  Citation text
  Permalink string
  Repository string
  Rights string
  IsPublishable boolean
}

// ==== EXTERNAL DRUPAL FILES ====

Table Files {
  id string [pk]
  Label string
  Timestamp datetime
  User string
  Comment text
  Size int
  Sha1 string
  Mime string
  Url string
}

// ==== RESEARCH ENTITIES ====

Table Person {
  Code string [pk]
  FirstName string
  LastName string
  BirthDate date
  DeathDate date
  Biography text
  Contact text
  Notes text
}

Table Organisation {
  Code string [pk]
  Name string
  Place string [ref: > Place.Code]
  Description text
  Contact text
  Notes text
}

Table Place {
  Code string [pk]
  Parent string [ref: > Place.Code]
  Label string
  Type string
  Latitude float
  Longitude float
  Description text
  Notes text
}

Table Chapter {
  Code string [pk]
  Description string
  Parent string [ref: > Chapter.Code]
  StartYear integer
  EndYear integer
  Notes text
}

// ==== LOOKUP TABLES ====

Table ObjectType {
  Code string [pk]
  Description text
}

Table AssetSourceType {
  Code string [pk]
  Label string
  Description text
}

Table AssetType {
  Code string [pk]
  Name string
  Description text
}

Table AssetRole {
  Code string [pk]
  Name string
  Description text
}

Table PersonRole {
  Code string [pk]
  Name string
  Description text
}

Table OrganisationRole {
  Code string [pk]
  Name string
  Description text
}

Table Keywords {
  Code string [pk]
  Name string
  Description text
}

// ==== RELATIONSHIP TABLES (Junctions) ====

Table ObjectAsset {
  id string [pk]
  Object string [ref: > Object.Code]
  Asset string [ref: > Asset.Code]
  Role string [ref: > AssetRole.Code]
  IsPreferred boolean
}

Table PersonAsset {
  id string [pk]
  Person string [ref: > Person.Code]
  Asset string [ref: > Asset.Code]
}

Table OrganisationAsset {
  id string [pk]
  Organisation string [ref: > Organisation.Code]
  Asset string [ref: > Asset.Code]
}

Table OjectChapter {
  id string [pk]
  Object string [ref: > Object.Code]
  Chapter string [ref: > Chapter.Code]
}

Table ObjectPerson {
  id string [pk]
  Object string [ref: > Object.Code]
  Person string [ref: > Person.Code]
  Role string [ref: > PersonRole.Code]
}

Table ObjectOrganisation {
  id string [pk]
  Object string [ref: > Object.Code]
  Organisation string [ref: > Organisation.Code]
  Role string [ref: > OrganisationRole.Code]
}

Table PersonOrganisationRole {
  id string [pk]
  Person string [ref: > Person.Code]
  Organisation string [ref: > Organisation.Code]
  Role string [ref: > OrganisationRole.Code]
}

Table ObjectKeyword {
  id string [pk]
  Object string [ref: > Object.Code]
  Keyword string [ref: > Keywords.Code]
}

Table ObjectHolder {
  id string [pk]
  Object string [ref: > Object.Code]
  Person string [ref: > Person.Code]
  Organisation string [ref: > Organisation.Code]
}

Appendix - 2: Modules already enabled in our Drupal 11 configuration - version 20260319 =

mngr@localhost:/var/www/drupal$ drush pm:list --status=enabled
  ---------------- ----------------------------------------------------------------------- --------- ---------- 
  Package          Name                                                                    Status    Version   
 ---------------- ----------------------------------------------------------------------- --------- ---------- 
  Core             Announcements (announcements_feed)                                      Enabled   11.3.5    
  Core             Automated Cron (automated_cron)                                         Enabled   11.3.5    
  Core             BigPipe (big_pipe)                                                      Enabled   11.3.5    
  Core             Block (block)                                                           Enabled   11.3.5    
  Core             Block Content (block_content)                                           Enabled   11.3.5    
  Core             Breakpoint (breakpoint)                                                 Enabled   11.3.5    
  Core             CKEditor 5 (ckeditor5)                                                  Enabled   11.3.5    
  Core             Comment (comment)                                                       Enabled   11.3.5    
  Core             Configuration Manager (config)                                          Enabled   11.3.5    
  Core             Contact (contact)                                                       Enabled   11.3.5    
  Core             Contextual Links (contextual)                                           Enabled   11.3.5    
  Field types      Datetime (datetime)                                                     Enabled   11.3.5    
  Field types      Datetime Range (datetime_range)                                         Enabled   11.3.5    
  Core             Database Logging (dblog)                                                Enabled   11.3.5    
  Core             Internal Dynamic Page Cache (dynamic_page_cache)                        Enabled   11.3.5    
  Core             Text Editor (editor)                                                    Enabled   11.3.5    
  Core             Field (field)                                                           Enabled   11.3.5    
  Core             Field UI (field_ui)                                                     Enabled   11.3.5    
  Field types      File (file)                                                             Enabled   11.3.5    
  Core             Filter (filter)                                                         Enabled   11.3.5    
  Core             Help (help)                                                             Enabled   11.3.5    
  Core             History (history)                                                       Enabled   11.3.5    
  Field types      Image (image)                                                           Enabled   11.3.5    
  Core             Inline Form Errors (inline_form_errors)                                 Enabled   11.3.5    
  Core             Layout Builder (layout_builder)                                         Enabled   11.3.5    
  Core             Layout Discovery (layout_discovery)                                     Enabled   11.3.5    
  Field types      Link (link)                                                             Enabled   11.3.5    
  Core             Media (media)                                                           Enabled   11.3.5    
  Core             Media Library (media_library)                                           Enabled   11.3.5    
  Core             Custom Menu Links (menu_link_content)                                   Enabled   11.3.5    
  Core             Menu UI (menu_ui)                                                       Enabled   11.3.5    
  Core             MySQL (mysql)                                                           Enabled   11.3.5    
  Core             Node (node)                                                             Enabled   11.3.5    
  Field types      Options (options)                                                       Enabled   11.3.5    
  Core             Internal Page Cache (page_cache)                                        Enabled   11.3.5    
  Core             Path (path)                                                             Enabled   11.3.5    
  Core             Path alias (path_alias)                                                 Enabled   11.3.5    
  Core             Responsive Image (responsive_image)                                     Enabled   11.3.5    
  Core             Search (search)                                                         Enabled   11.3.5    
  Core             Shortcut (shortcut)                                                     Enabled   11.3.5    
  Core             System (system)                                                         Enabled   11.3.5    
  Core             Taxonomy (taxonomy)                                                     Enabled   11.3.5    
  Field types      Text (text)                                                             Enabled   11.3.5    
  Core             Toolbar (toolbar)                                                       Enabled   11.3.5    
  Core             Update Status (update)                                                  Enabled   11.3.5    
  Core             User (user)                                                             Enabled   11.3.5    
  Core             Views (views)                                                           Enabled   11.3.5    
  Core             Views UI (views_ui)                                                     Enabled   11.3.5    
  Core             Workspaces (workspaces)                                                 Enabled   11.3.5    
  Core             Workspaces UI (workspaces_ui)                                           Enabled   11.3.5    
  Field types      Address (address)                                                       Enabled   2.0.4     
  Development      Asset Injector (asset_injector)                                         Enabled   8.x-2.21  
  Field types      Color Field (color_field)                                               Enabled   3.0.2     
  Other            Computed Field (computed_field)                                         Enabled   4.0.0     
  Other            Contact Formatter (contact_formatter)                                   Enabled   2.0.4     
  Core             Dashboard (dashboard)                                                   Enabled   2.2.0     
  Field types      Entity Reference Revisions (entity_reference_revisions)                 Enabled   8.x-1.14  
  Fields           Field Group (field_group)                                               Enabled   4.0.0     
  File metadata    File metadata manager (file_mdm)                                        Enabled   3.2.0     
  File metadata    File metadata - EXIF (file_mdm_exif)                                    Enabled   3.2.0     
  File metadata    File metadata - Font (file_mdm_font)                                    Enabled   3.2.0     
  Geocoding        Geocoder (geocoder)                                                     Enabled   8.x-4.31  
  Geocoding        Geocoder Address (geocoder_address)                                     Enabled   8.x-4.31  
  Geocoding        Geocoder Field (geocoder_field)                                         Enabled   8.x-4.31  
  Geocoding        Geocoder Geofield (geocoder_geofield)                                   Enabled   8.x-4.31  
  Geofield         Geofield (geofield)                                                     Enabled   10.3.4    
  Geolocation      Geolocation (geolocation)                                               Enabled   8.x-3.14  
  Geolocation      Geolocation - Address (geolocation_address)                             Enabled   8.x-3.14  
  Geolocation      Geolocation - Baidu Maps (geolocation_baidu)                            Enabled   8.x-3.14  
  Geolocation      Geolocation - Here Maps (geolocation_here)                              Enabled   8.x-3.14  
  Geolocation      Geolocation - Leaflet (geolocation_leaflet)                             Enabled   8.x-3.14  
  Other            Gin Toolbar (gin_toolbar)                                               Enabled   3.0.3     
  Media            Image Effects (image_effects)                                           Enabled   5.0.0     
  Media            ImageMagick (imagemagick)                                               Enabled   5.0.1     
  jQuery UI        jQuery UI (jquery_ui)                                                   Enabled   8.x-1.8   
  jQuery UI        jQuery UI Autocomplete (jquery_ui_autocomplete)                         Enabled   2.1.0     
  jQuery UI        jQuery UI Menu (jquery_ui_menu)                                         Enabled   2.1.0     
  User interface   Klaro Cookie & Consent Manager (klaro)                                  Enabled   3.0.8     
  Geofield         Leaflet (leaflet)                                                       Enabled   10.4.4    
  Geofield         Leaflet Markercluster (leaflet_markercluster)                           Enabled   10.4.4    
  Geofield         Leaflet Views (leaflet_views)                                           Enabled   10.4.4    
  User interface   Linkit (linkit)                                                         Enabled   7.0.13    
  Other            Media Library Form Element (media_library_form_element)                 Enabled   2.1.4     
  Paragraphs       Paragraphs Type Permissions (paragraphs_type_permissions)               Enabled   8.x-1.20  
  Paragraphs       Paragraphs (paragraphs)                                                 Enabled   8.x-1.20  
  Paragraphs       Paragraph Bundle 3D Carousel (paragraph_bundle_3d_carousel)             Enabled   1.0.16    
  Paragraphs       Paragraph Bundle 3D Flip Box (paragraph_bundle_3d_flip_box)             Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Accordion (paragraph_bundle_accordion)                 Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Alert (paragraph_bundle_alert)                         Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Block (paragraph_bundle_block)                         Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Block Content (paragraph_bundle_block_content)         Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Card (paragraph_bundle_card)                           Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Carousel (paragraph_bundle_carousel)                   Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Contact Form (paragraph_bundle_contact_form)           Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Content (paragraph_bundle_content)                     Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Grid (paragraph_bundle_grid)                           Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Hero (paragraph_bundle_hero)                           Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Icon (paragraph_bundle_icon)                           Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Image (paragraph_bundle_image)                         Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Image Background (paragraph_bundle_image_background)   Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Image Grid (Image Gallery - Lightbox)                  Enabled   1.0.16    
                   (paragraph_bundle_image_grid)                                                               
  Paragraphs       Paragraph Bundle Image Overlay (paragraph_bundle_image_overlay)         Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Layout (paragraph_bundle_layout)                       Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Modal (paragraph_bundle_modal)                         Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Node Reference (paragraph_bundle_node_reference)       Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Parallax (paragraph_bundle_parallax)                   Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Slideshow (paragraph_bundle_slideshow)                 Enabled   1.0.16    
  Paragraphs       Paragraph Bundle Tabs (paragraph_bundle_tabs)                           Enabled   1.0.16    
  Paragraphs       Paragraphs Bundles (paragraphs_bundles)                                 Enabled   1.0.16    
  Mail             SMTP Authentication Support (smtp)                                      Enabled   8.x-1.4   
  Solo Suite       Solo Utilities (solo_utilities)                                         Enabled   1.0.6     
  Other            Sophron (sophron)                                                       Enabled   3.1.0     
  Media            SVG Image Responsive (svg_image_responsive)                             Enabled   3.2.2     
  Media            SVG image (svg_image)                                                   Enabled   3.2.2     
  Costasano        Costasano Asset (costasano_asset)                                       Enabled             
  Heritage         Heritage Codes (heritage_codes)                                         Enabled   1.0.0     
  Heritage         Heritage Tweaks (heritage_tweaks)                                       Enabled             
  Core             Claro (claro)                                                           Enabled   11.3.5    
  Core             Olivero (olivero)                                                       Enabled   11.3.5    
                   Gin (gin)                                                               Enabled   5.0.12    
  Solo             Solo (solo)                                                             Enabled   1.0.31    
 ---------------- ----------------------------------------------------------------------- --------- ----------