ICT:Drupal Blueprint - Version 6.5
Costasano Heritage Project — Drupal 11 Architecture & Workflow Blueprint (v6.0)
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.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
- 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.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
Next Major step: HeritageObject and Person
Now that Chapter, Place, Organisation and Asset are stable it is time for a next major step. HeritageObject, Drupal called Object, is the next challenge due to the fact it has a many to many relationship with Asset, is recursive and also linked to a serious number of other entities. One of these is Person, not yet prepared for. This will be the first next step.
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 Challenges: ToDo
- choice of PK for Person
- realisation of content type and view
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.
Challenges: ToDo - choice of PK? Yes or now different from Object Title including - implementation of a many to many relationship between Object and Asset - Objects can be structures (recursiveness) - One digital Asset is a prefered Asset and should link to that Aasset and the children of that Asset - We opt to chose the "top" Asset in the asset structure as orefered Asset (the Asset without parent)
Step 7: Object & Advanced Relationships
Type:
- Custom Content Entities
- Role-based 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
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.
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
- 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 7th 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.
End of Blueprint
Appendix - 1: 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 Counter
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
}
Appendix - 2: 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.
Appendix - 4: 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
---------------- ------------------------------------------------------- --------- ----------