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: Completing help functions
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. 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
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 Dashboard page operational with minimal set of attributes
- adding automatic numbering for asset
- hiding FK fields after creation
ToDO:
- adding supplementary attributes - especially media files
- prefil the code field
- implementing logic
See appendix
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.
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: Automatic Asset Identifier Generation
Purpose
Each Asset receives a unique, stable identifier automatically generated by the system when the Asset is created. This identifier is the permanent reference used across the Costasano Heritage Project.
Identifiers must remain stable over time and must never be modified once assigned.
---
Identifier Structure
The identifier follows the structure:
``` ChapterCode-ContextCode-Sequence ```
Example:
``` CH00-OOSTEN-00001 CH01a-HYDRO1-00002 ```
Components:
| Component | Meaning | | ----------- | --------------------------- | | ChapterCode | Historical timeline segment | | ContextCode | Place OR Organisation | | Sequence | Global asset counter |
The identifier is stored in the Drupal Title field of the Asset entity.
---
Sequence Counter
The sequence is a global counter stored in the field:
``` field_as_counter ```
Properties:
- integer value
- automatically incremented
- formatted as a five-digit number
- padded with leading zeros
Example:
``` 00001 00002 00003 ```
Sequence generation rule:
``` next counter = MAX(existing counter) + 1 ```
Sequence gaps are acceptable if records are deleted by the system administrator.
---
Context Determination
The context part of the identifier is derived from one of two authority entities:
- Place
- Organisation
Exactly one must be selected when creating the Asset.
Examples:
``` CH01ab-OOSTEN-01234 CH02-HYDRO1-01235 ```
The context code is taken from the label of the referenced authority entity.
---
Generation Workflow
When a new Asset is saved:
1. The system reads the highest existing counter. 2. The counter is incremented. 3. The sequence number is formatted to five digits. 4. The identifier is assembled:
``` ChapterCode-ContextCode-Sequence ```
5. The identifier is written to the Title field.
This process occurs automatically during the Drupal entity presave event.
---
Structural Field Immutability
After the Asset is created, the following fields become immutable:
``` Chapter Place Organisation ```
These fields are removed from the edit form to prevent accidental modification.
If a mistake was made during creation:
- the incorrect Asset must be deleted by the system administrator
- a new Asset must be created.
---
Design Rationale
This approach ensures:
- deterministic identifier generation
- minimal cognitive load for users
- long-term stability of references
- compatibility with URLs, exports, and external publications.
Identifiers therefore function as permanent archival references within the system.
Appendix - 2: 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 - 3: 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
---------------- ------------------------------------------------------- --------- ----------