ICT:Drupal Blueprint - Version 6.5

Costasano Heritage Project — Drupal 11 Architecture & Workflow Blueprint (v5.3)

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).

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

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 (IIS + ARR, SSL offloading)
• Web Server: AlmaLinux 10.1 (Apache 2.4, PHP 8.3, PHP-FPM)
• Database Server: AlmaLinux 10.1 (MariaDB 10.11+)
• SELinux: Enforcing
• PHP-FPM: Per-site pools
• Filesystem: Hardened

Operational Constants

• Site URL: https://research.costasano.club
• Drupal project root: /var/www/drupal
• Drupal web root: /var/www/drupal/web

---

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. This order is mandatory.

---

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.y CH01, CH01.1
• recursive (parent/child) one level only
• 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 ToDO: -

---

Step 2: Place (Spatial Authority)

Type:

• Drupal Custom Content Entity (authority)

Characteristics:

• recursive (parent places)
• stable Code (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. ToDo: waiting for Providers to be used. Problems with Drupal 11.3.4 not yest accepting some essential software to make this work.

---

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:

1. adding map view based on Place coordinnates

---

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 4-digit counter (asset sequence only)

Example:

CH03-OOSTEN-0007

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

Status: Drupal Context Type and Dashboard page operational with minimal set of attributes ToDO:

1. adding supplementary attributes
2. adding automatic numbering for asset

---

Step 5: Object & Advanced Relationships (Deferred)

Type:

• Custom Content Entities
• Role-based relationships

This step is explicitly deferred until asset logic is proven and Places is complete

---

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

For Assets:

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

---

Help & Guidance Strategy

Help must be:

• contextual
• non-intrusive
• always available

Mechanisms:

• field descriptions
• ℹ️ icons
• collapsible help sections

No separate manuals.

---

Automation & Logic

Automation is handled via:

• Drupal configuration
• ECA workflows
• Custom event subscribers if required

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.

---

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
• 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
• No experimental or unstable admin themes are permitted

---

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

Implementation Status - March 5th 2026)

Entities implemented:

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

All entities include:

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

Automation for DigitalAsset identifiers is not yet implemented.

appendix: Data Model - Core Mermaid verion 4.4

The version 4.4 has been adapted to Drupal naming used or planned to use.

erDiagram
    OBJECT ||--o{ ASSET : "through ObjectAsset"
    OBJECT ||--o{ PERSON : "through ObjectPerson"
    OBJECT ||--o{ ORGANISATION : "through ObjectOrganisation"
    OBJECT ||--o{ CHAPTER : "through ObjectChapter"
    OBJECT ||--o{ KEYWORDS : "through ObjectKeyword"
    OBJECT ||--o{ PERSON : "through ObjectHolder"
    OBJECT ||--o{ ORGANISATION : "through ObjectHolder"
    OBJECT }o--|| PLACE : "located in"
    OBJECT }o--|| OBJECT : "has parent"
    
    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
        list   Type
        string Address
        float Latitude, Longitude
        text Description
        text Notes
    }
    
    CHAPTER {
        string Code PK
        string Name
        string Parent FK
        integer StartYear
        integer EndYear
        text Description
        text Notes
    }
    
 

Lessons learned on feb 27 2026

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.

Restart from scratch after that day, restoring of the full virtual disks for both machines dated 26 feb.

Conclusion of the day were chatgpt promises for restarting.

Tomorrow I will:

• avoid cleverness
• 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.

Important AI protocal

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.

Modules already enabled in our Drupal 11 configuration =

mmngr@localhost:/var/www/drupal$ drush pm:list --status=enabled
 ---------------- ------------------------------------------------------- --------- ---------- 
  Package          Name                                                    Status    Version   
 ---------------- ------------------------------------------------------- --------- ---------- 
  Core             Announcements (announcements_feed)                      Enabled   11.3.4    
  Core             Automated Cron (automated_cron)                         Enabled   11.3.4    
  Core             BigPipe (big_pipe)                                      Enabled   11.3.4    
  Core             Block (block)                                           Enabled   11.3.4    
  Core             Block Content (block_content)                           Enabled   11.3.4    
  Core             Breakpoint (breakpoint)                                 Enabled   11.3.4    
  Core             CKEditor 5 (ckeditor5)                                  Enabled   11.3.4    
  Core             Comment (comment)                                       Enabled   11.3.4    
  Core             Configuration Manager (config)                          Enabled   11.3.4    
  Core             Contact (contact)                                       Enabled   11.3.4    
  Core             Contextual Links (contextual)                           Enabled   11.3.4    
  Field types      Datetime (datetime)                                     Enabled   11.3.4    
  Field types      Datetime Range (datetime_range)                         Enabled   11.3.4    
  Core             Database Logging (dblog)                                Enabled   11.3.4    
  Core             Internal Dynamic Page Cache (dynamic_page_cache)        Enabled   11.3.4    
  Core             Text Editor (editor)                                    Enabled   11.3.4    
  Core             Field (field)                                           Enabled   11.3.4    
  Core             Field UI (field_ui)                                     Enabled   11.3.4    
  Field types      File (file)                                             Enabled   11.3.4    
  Core             Filter (filter)                                         Enabled   11.3.4    
  Core             Help (help)                                             Enabled   11.3.4    
  Core             History (history)                                       Enabled   11.3.4    
  Field types      Image (image)                                           Enabled   11.3.4    
  Core             Inline Form Errors (inline_form_errors)                 Enabled   11.3.4    
  Core             Layout Builder (layout_builder)                         Enabled   11.3.4    
  Core             Layout Discovery (layout_discovery)                     Enabled   11.3.4    
  Field types      Link (link)                                             Enabled   11.3.4    
  Core             Media (media)                                           Enabled   11.3.4    
  Core             Media Library (media_library)                           Enabled   11.3.4    
  Core             Custom Menu Links (menu_link_content)                   Enabled   11.3.4    
  Core             Menu UI (menu_ui)                                       Enabled   11.3.4    
  Core             MySQL (mysql)                                           Enabled   11.3.4    
  Core             Node (node)                                             Enabled   11.3.4    
  Field types      Options (options)                                       Enabled   11.3.4    
  Core             Internal Page Cache (page_cache)                        Enabled   11.3.4    
  Core             Path (path)                                             Enabled   11.3.4    
  Core             Path alias (path_alias)                                 Enabled   11.3.4    
  Core             Responsive Image (responsive_image)                     Enabled   11.3.4    
  Core             Search (search)                                         Enabled   11.3.4    
  Core             Shortcut (shortcut)                                     Enabled   11.3.4    
  Core             System (system)                                         Enabled   11.3.4    
  Core             Taxonomy (taxonomy)                                     Enabled   11.3.4    
  Field types      Text (text)                                             Enabled   11.3.4    
  Core             Toolbar (toolbar)                                       Enabled   11.3.4    
  Core             Update Status (update)                                  Enabled   11.3.4    
  Core             User (user)                                             Enabled   11.3.4    
  Core             Views (views)                                           Enabled   11.3.4    
  Core             Views UI (views_ui)                                     Enabled   11.3.4    
  Core             Workspaces (workspaces)                                 Enabled   11.3.4    
  Core             Workspaces UI (workspaces_ui)                           Enabled   11.3.4    
  Field types      Address (address)                                       Enabled   2.0.4     
  Field types      Color Field (color_field)                               Enabled   3.0.2     
  Other            Contact Formatter (contact_formatter)                   Enabled   2.0.4     
  Core             Dashboard (dashboard)                                   Enabled   2.2.0     
  Field types      Entity Reference Revisions                              Enabled   8.x-1.14  
                   (entity_reference_revisions)                                                
  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.30  
  Geocoding        Geocoder Address (geocoder_address)                     Enabled   8.x-4.30  
  Geocoding        Geocoder Field (geocoder_field)                         Enabled   8.x-4.30  
  Geocoding        Geocoder Geofield (geocoder_geofield)                   Enabled   8.x-4.30  
  Geofield         Geofield (geofield)                                     Enabled   10.3.3    
  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     
  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    
  Paragraphs       Paragraphs Type Permissions                             Enabled   8.x-1.20  
                   (paragraphs_type_permissions)                                               
  Paragraphs       Paragraphs (paragraphs)                                 Enabled   8.x-1.20  
  Paragraphs       Paragraph Bundle 3D Carousel                            Enabled   1.0.15    
                   (paragraph_bundle_3d_carousel)                                              
  Paragraphs       Paragraph Bundle 3D Flip Box                            Enabled   1.0.15    
                   (paragraph_bundle_3d_flip_box)                                              
  Paragraphs       Paragraph Bundle Accordion                              Enabled   1.0.15    
                   (paragraph_bundle_accordion)                                                
  Paragraphs       Paragraph Bundle Alert (paragraph_bundle_alert)         Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Block (paragraph_bundle_block)         Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Block Content                          Enabled   1.0.15    
                   (paragraph_bundle_block_content)                                            
  Paragraphs       Paragraph Bundle Card (paragraph_bundle_card)           Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Carousel (paragraph_bundle_carousel)   Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Contact Form                           Enabled   1.0.15    
                   (paragraph_bundle_contact_form)                                             
  Paragraphs       Paragraph Bundle Content (paragraph_bundle_content)     Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Grid (paragraph_bundle_grid)           Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Hero (paragraph_bundle_hero)           Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Icon (paragraph_bundle_icon)           Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Image (paragraph_bundle_image)         Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Image Background                       Enabled   1.0.15    
                   (paragraph_bundle_image_background)                                         
  Paragraphs       Paragraph Bundle Image Grid (Image Gallery -            Enabled   1.0.15    
                   Lightbox) (paragraph_bundle_image_grid)                                     
  Paragraphs       Paragraph Bundle Image Overlay                          Enabled   1.0.15    
                   (paragraph_bundle_image_overlay)                                            
  Paragraphs       Paragraph Bundle Layout (paragraph_bundle_layout)       Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Modal (paragraph_bundle_modal)         Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Node Reference                         Enabled   1.0.15    
                   (paragraph_bundle_node_reference)                                           
  Paragraphs       Paragraph Bundle Parallax (paragraph_bundle_parallax)   Enabled   1.0.15    
  Paragraphs       Paragraph Bundle Slideshow                              Enabled   1.0.15    
                   (paragraph_bundle_slideshow)                                                
  Paragraphs       Paragraph Bundle Tabs (paragraph_bundle_tabs)           Enabled   1.0.15    
  Paragraphs       Paragraphs Bundles (paragraphs_bundles)                 Enabled   1.0.15    
  Solo Suite       Solo Utilities (solo_utilities)                         Enabled   1.0.6     
  Media            SVG Image Responsive (svg_image_responsive)             Enabled   3.2.2     
  Media            SVG image (svg_image)                                   Enabled   3.2.2     
  Core             Claro (claro)                                           Enabled   11.3.4    
  Core             Olivero (olivero)                                       Enabled   11.3.4    
                   Gin (gin)                                               Enabled   5.0.12    
  Solo             Solo (solo)                                             Enabled   1.0.30    
 ---------------- ------------------------------------------------------- --------- ----------