Architecture

Architecture

Curious about what's under the hood, or planning to extend Studio? This page is for you. The short version: Studio is plain Drupal, built the Drupal way: entities, fields, plugins, services, config and recipes. No forks, no magic.

The modules

PlantUML source (rendered live by the PlantUML for GitHub extension)

@startuml
skinparam backgroundColor transparent
skinparam defaultFontName Verdana
skinparam shadowing false
skinparam componentStyle rectangle
skinparam component {
  BackgroundColor #ffffff
  BorderColor #335999
}
skinparam ArrowColor #8fa6cc
package "Drupal 11 core" as core #f4f6fa {
  [Content moderation\n& workflows] as cm
  [Entity API · Views\nFields · Files] as api
}
package "Divengine Studio" #eef2fb {
  [divengine_core\nshared UI components,\nsequences, permissions] as dcore
  [divengine_artifact\nartifacts & types] as art
  [divengine_knowledge\nknowledge taxonomies] as kn
  [divengine_traceability\ntrace links & types] as tr
  [divengine_modeler\ndiagram platform] as mod
  [divengine_modeler_bpmn] as bpmn
  [divengine_modeler_uml] as uml
  [divengine_diagram_embed\ndiagrams in text] as emb
  [divengine_process\nUnified Process] as up
  [divengine_qa\ntest management] as qa
  [divengine_project\nprojects & tasks] as prj
  [divengine_timesheet\ntimesheets] as ts
  [divengine_mcp\n(optional)] as mcp
  [divengine_studio_theme] as theme
}
art --> dcore
kn --> art
tr --> dcore
mod --> dcore
bpmn --> mod
uml --> mod
emb --> mod
up --> art
up --> tr
qa --> up
qa --> tr
prj --> tr
prj --> dcore
ts --> prj
art --> cm
up --> api
mcp ..> up : reads via\nJSON:API
@enduml

Module	Responsibility
divengine_core	Shared services (code sequences), permissions and the UI components (badges, status bar, stat cards, sections) every page uses.
divengine_artifact	The artifact entity with its types (bundles), revisions and editorial lifecycle.
divengine_knowledge	Knowledge taxonomies: domains, source types, standard bodies.
divengine_traceability	The trace_link entity, trace link types and the trace panel shown on records.
divengine_modeler	The diagram platform: diagram entity, notation plugins, safe SVG previews, element links.
divengine_modeler_bpmn / _uml	The BPMN (bpmn-js) and UML (PlantUML in the browser) notations.
divengine_diagram_embed	The CKEditor 5 Diagram button and the <drupal-diagram> filter.
divengine_process	The Unified Process: Developments, phases, iterations, milestones, activities, change requests, baselines, development cases, readiness.
divengine_qa	Test management and the verification bridge to the Unified Process.
divengine_project	Project management: projects, subprojects, tasks, subtasks, stages, task types, boards; related tasks as traces; comments.
divengine_timesheet	Timesheet entries, allocated vs spent time, timer, weekly grid, reports.
divengine_thread	Discussion with attachments on every record (core comments), side panel.
divengine_articles	Knowledge base: articles (nodes) in a hierarchy, access by Development through node grants.
divengine_source	Code Source: repositories, refs and snapshots; index tables; code browser; MCP code_* tools.
divengine_database	Database schemas: databases and immutable snapshots fed through a normalized contract (adapters per analyzer, SchemaSpy included), fact tables, findings, JointJS + ELK schema explorer, schema evolution, MCP database_* tools.
divengine_mcp	Optional: service account and token for the MCP server.
divengine_studio_theme	The workspace theme (Divengine blue #335999, Verdana, the [[]] mark). Gin stays as admin theme.

Dependencies point one way: divengine_artifact and divengine_traceability know nothing about the process; divengine_process builds on them; divengine_qa builds on the process.

Design decisions that shape everything

flowchart TB
    A["<b>Knowledge = artifact bundles</b><br/>requirements, use cases, rules…<br/>one entity type, many types"]
    B["<b>Process structure = own entities</b><br/>Development, Iteration, Milestone,<br/>Activity, Change request, Baseline"]
    C["<b>trace_link is the only relationship record</b><br/>typed, directed, revisioned"]
    D["<b>Visibility follows the Development</b><br/>entity access + query alter"]
    E["<b>Lifecycle engine</b><br/>transitions with guards, effects<br/>and confirmations"]
    F["<b>Distribution as recipes</b><br/>install = one command"]
    A --- C
    B --- C
    B --- D
    B --- E

Loading

• Artifacts are bundles of one entity type. Adding a kind of knowledge is configuration, not code.
• Process records get their own entity types, because they have real behaviour (state machines, rules) rather than just fields.
• Traces are the only way to relate things. No hidden entity-reference fields pretending to be relationships.
• Visibility follows the Development everywhere: page access, lists, Views, counts, traces.
• State changes go through a lifecycle engine with guards ("write the decision rationale first"), effects (record who decided), and optional confirmations.
• Write rules live in the entities: services check workflow rules and save as trusted; any other path (forms, REST, JSON:API) hits validation constraints with the same rules.
• Revisions are Drupal revisions; baselines store exact revision IDs and protect them.

The full reasoning lives in the ADRs of the repository: docs/architecture.

Request flow of a record page

sequenceDiagram
    participant B as Browser
    participant R as Drupal router
    participant A as Access handler
    participant V as View builder
    participant C as SDC components
    B->>R: GET /qa/run/5
    R->>A: may this user view RUN-0005?
    A->>A: Development visible? assigned tester or lead?
    A-->>R: allowed
    R->>V: build the page
    V->>V: status bar, cards, sections, actions<br/>(only the buttons that apply now)
    V->>C: badge · status-bar · stat-card · section
    C-->>B: HTML (cached per user, invalidated by cache tags)

Loading

Extending Studio

• New artifact type: configuration only (admin UI or config YAML).
• New readiness criterion: a ReadinessCriterion plugin in any module (src/Plugin/ReadinessCriterion), then reference it from a Development case.
• New Development-scoped entity type: give it a development field and add it with hook_divengine_process_scoped_types_alter(); visibility comes for free.
• New trace end: hook_divengine_trace_end_types_alter().
• Discussion on a new record type: hook_divengine_thread_types_alter().
• New [[CODE]] target: hook_divengine_code_fields_alter() (entity type → code field).
• New notation: a modeler notation plugin, like the BPMN and UML modules.
• Extend a Development case from a recipe: the addLines config action.

Tech stack

Drupal 11 · PHP 8.4 · PostgreSQL · Composer · Drush 13 · Single Directory Components · CKEditor 5 · bpmn-js · PlantUML (in the browser) · PHPUnit kernel tests · Playwright for screenshots.