Skip to content

Dédalo v7 Documentation

This is the manual for Dédalo v7

Running v6? Its manual is kept, unchanged, at dedalo.dev/docs/v6/. Use the version selector in the header to move between them.

Dédalo is a Free and Open Source Cultural Heritage Management System for archives, censuses, inventories and catalogs — archaeology, ethnology, oral memory, numismatics and more. Unlike a generic CMS, it is built to produce good data and publish it.

Its defining trait is an active ontology: the data schema, the relations between data, the components and tools, and even much of the program behavior are defined as nodes in a thesaurus-like hierarchy and resolved at execution time. Change the ontology and Dédalo's behavior changes — usually without touching the database or the code.

Dédalo is two connected systems:

  • Work system — the private editing application (TypeScript/Bun server + JavaScript/HTML/CSS client) that manages the full catalog. Data is stored as JSONB in a PostgreSQL "matrix" table.
  • Diffusion system — a separate, public, flat copy of the data published to SQL/RDF/XML targets and served through a public API. Data flows one way only, work → diffusion.

New to the vocabulary (section, component, tipo, locator, sqo, rqo, ddo)? Read the Introduction & core hub and the Glossary first.

Not a developer? Dédalo in plain language explains the whole system — where it lives, how a record travels, what the APIs are, and what the AI layer does — in four diagrams and one text written for curators, archivists and humanities researchers. Start there, and come back here when you want the detail.

Where the engine came from. Dédalo v7's server was rebuilt from scratch in TypeScript on the Bun runtime, replacing the engine that served the project for two decades. If you want the why, what and the new foundation — written for developers and humanities readers alike — read The v7 rewrite. You do not need it to use, install or extend Dédalo: everything else in this manual documents the engine as it is today.

Reading paths by role

Pick the path that matches what you are trying to do. Each is a short, ordered list — read top to bottom.

1. New developer — understand the architecture

  1. The v7 rewrite — where the engine came from and why it was rebuilt (background; skip it if you just want to build)
  2. Introduction (core hub) — what Dédalo is, the nomenclature, the active ontology
  3. Architecture Overview — how it all fits together: two systems, the matrix data model, server build → client render
  4. Data model — how a value actually lives: the JSON/JSONB foundation, the typed matrix columns and the consolidated v7 value item, with a page per data type
  5. Glossary — the full nomenclature reference
  6. Ontology — the active schema that drives everything
  7. Sections and Components — the table and field abstractions
  8. Development guide — ecosystem, code style, commit and testing conventions

2. Integrator — consume the APIs

  1. Dédalo API v1 (work system) — the JSON API entry point and request flow
  2. Request Query Object (RQO) — the request structure callers send
  3. Search Query Object (SQO) — the JSON abstraction of SQL queries
  4. DD Object (ddo) and Locator — the data-pointer primitives
  5. API class reference — per-class actions (core, tools, ts, utils, components, manager)
  6. The diffusion engine — the dd_diffusion_api publication action set served by the work API, plus RQO field mapping
  7. Publication API — serving published data to websites, integrations and AI agents. Use v2 (Bun/TypeScript: resource-oriented REST, bracketed filter DSL, RFC 9457 errors, ETag/Link caching, batch and MCP) for all new integrations; v1 is legacy
  8. RAG & semantic search — the dd_rag_api action set (semantic search, grounded ask, object-image similarity) and the agent/MCP surface; the operational cookbook has the request recipes
  9. AI Assistant — the in-app chat agent; drive it from your own code via dd_mcp_api (agent_models / agent_chat_stream / agent_apply), with the full SSE protocol + HTTP recipes

3. Core developer — extend Dédalo

  1. Development guide — conventions, code style, breaking-change detection, metrics
  2. Components reference — typologies, base classes, per-component docs
  3. Sections and Areas — record containers and top-level groupers
  4. Data model — the value-item contract under every component: typed matrix columns, the {id, lang?, value|locator} envelope, server-minted item ids, and a page per data type (string, number, date, IRI, geo, media, relations, misc)
  5. Ontology authoring — defining sections, components, relations and tools as nodes
  6. Extending Dédalo — the ontology-first cookbooks: add a component, section, area, service, widget (+ the component_info widget cookbook of copy-paste recipes)
  7. Request Config + examples — how data is retrieved and displayed
  8. Client side — instances, lifecycle, render and views, data/event managers
  9. Tools — build a tool: register.json, server contract, JS lifecycle, security, tool catalog
  10. Media pipeline and Internationalization — the media-file lifecycle and the two translation planes
  11. Testing — the test layers run by bun test (unit gates, parity against the frozen fixture store, the client browser harness), the tripwires that enforce every invariant, and how to write a server test
  12. Services and System & infrastructure — shared services, persistence, caching, workers

4. System administrator — install, configure, operate

  1. Installation — start here: server sizing, prerequisites, and your path — a production server, Docker, or a laptop in ten minutes. Then the reverse proxy, the installer reference, upgrading and troubleshooting
  2. Configuration — the one .env file: how it works, every setting, database, areas
  3. Media protection and search config — before you expose media to the internet: the two-rule access gate the web server enforces, and search tuning
  4. Management & maintenance — environments, root user, maintenance status, recovery mode
  5. Users, profiles & permissions — creating users and profiles, the 0–3 permission levels, how access is computed and enforced
  6. Backup + best practices — protecting the data
  7. Updates — updating code, data, ontology
  8. Runtime — one long-lived process, per-request isolation, and what that means operationally
  9. Diffusion setup — configure the publication server: v2 deployment (.env, Apache/Nginx/standalone) for new servers, or the legacy v1 public API configuration and server config API
  10. RAG install & operations — provision the pgvector store, connect embedding/LLM sidecars, the full DEDALO_RAG_* config reference, and wire the index-drain cron
  11. AI Assistant — install, connect a model, configure, secure — turn on the in-app assistant, connect a cloud or local/private model, and control what may reach an external provider with the egress gate

5. Data curator / manager — work with the data

  1. Dédalo in plain language — the whole system without the jargon, and the ideas behind it for curators and humanities readers
  2. Introduction (core hub) and Glossary — the concepts and vocabulary
  3. Areas and Sections — how records are organised and edited
  4. Talk to your catalogue — the AI Assistant — search by meaning, understand a record, and (with confirmation) propose edits in plain language
  5. Thesaurus & ontology tree — managing hierarchies, descriptors and related terms
  6. Tools user guide — the day-to-day toolbox: import, export, print, media, transcription, translation, batch edits and record history, tool by tool
  7. Importing data and Exporting data — the import/export model behind those tools
  8. Media pipeline — how uploaded files become masters, derivatives, thumbnails and published media
  9. Diffusion data flow — deciding what is published and how; the native engine is what runs the publish
  10. Raspa Data Quality Score — assessing the quality of your catalog
  11. Backup and installing new hierarchies — day-to-day stewardship

Section index

Every documentation area, with a one-line description and an entry link. The core hub is the central landing for everything under core/.

Area Description Entry
In plain language The non-technical entry to the whole system: four diagrams (infrastructure, the journey of a record, the three APIs, the AI layer) plus the concepts written for curators and humanities researchers understanding/index.md
The rewrite Where the v7 engine came from, and why it was rebuilt — background, not required reading rewrite.md
Core hub Introduction, nomenclature, active ontology and the index of all core documentation core/index.md
Architecture overview How the two systems, the matrix data model and the active ontology fit together core/architecture_overview.md
Data model How a value lives: the JSONB foundation, typed matrix columns, the v7 value item, and a page per data type (string, number, date, IRI, geo, media, relations, misc) core/data_model/index.md
Glossary The full Dédalo nomenclature (section, component, tipo, locator, sqo, rqo, ddo, …) core/glossary.md
Areas Top-of-hierarchy groupers that gather sections and surface them in the menu core/areas/index.md
Sections The table abstraction: a group of records of the same kind, and its view modes core/sections/index.md
Components The field abstraction: typologies, base classes and the full per-component reference core/components/index.md
Ontology The active schema: sections, components, relations and tools defined as nodes core/ontology/index.md
Thesaurus The thesaurus hierarchy and ts_object tree model core/thesaurus/index.md
User interface The client render layer: page, menu, buttons, widgets, inspector, themes core/ui/index.md
Client Browser runtime: instances, lifecycle, render/views, data and event managers core/client/index.md
System & infrastructure Persistence, APIs, caching, search, security, media engine, dd_grid, login, backup core/system/index.md
Request Config How sections and components retrieve and display data (+ practical examples) core/request_config.md
RQO Request Query Object — the API request structure core/rqo.md
SQO Search Query Object — the JSON abstraction of SQL queries core/sqo.md
DD Object Normalized object used in RQO/SQO to build and instantiate elements core/dd_object.md
Locator The pointer/relation primitive between data core/locator.md
Events The server-side event system core/events.md
Importing data CSV/RDF/Dédalo import model and per-component conform contract core/importing_data.md
Exporting data The export atoms contract and flat-table export protocol core/exporting_data.md
Tools user guide Using every shipped tool in day-to-day work: import, export, print, media, transcription, translation, batch edits and record history tools/index.md
AI The AI hub: RAG & semantic search (concept + operational cookbook) and the in-app AI Assistant (install, connect a cloud or local/private model, egress privacy gate, use cases, HTTP/SSE integration cookbook) core/ai/index.md
Raspa score The data-quality evaluation metric core/raspa_score.md
Work API (v1) The JSON API entry point, RQO format and request handling api/dedalo_api_v1.md
API classes Per-class action reference (core, tools, ts, utils, components, manager) api/classes/dd_core_api.md
RQO field mapping Field-level mapping used when issuing API requests api/RQO_FIELD_MAPPING.md
Diffusion — the engine The publication engine built into the work server: plan compiler, resolver, parsers, format writers (SQL/CSV/JSON/Markdown/RDF/XML), durable job queue diffusion/native_engine.md
Diffusion parsers Cookbook + reference for the ontology parser functions (properties->process->parser): recipes with paste-ready JSON and in→out examples for all 33 fns diffusion/parsers.md
Diffusion (work side) Deciding what gets published and how: server topologies, the diffusion ontology with worked examples, resolve levels, output formats (Markdown) diffusion/diffusion_data_flow.md
Publication API Serving published data to the web — v2 (Bun/TypeScript, recommended) and legacy v1 diffusion/publication_api/index.md
Development Ecosystem, code style, commit/test conventions, breaking-change detection development/index.md
Documentation standards How Dédalo is documented: the code doc-block standard and the prose style guide development/code_documentation_standard.md
Extending Dédalo The ontology-first cookbooks: add a component, section, area, service or widget development/extending/index.md
Testing The bun test layers (unit gates, parity against the frozen fixture store, client browser harness) and the tripwires development/testing.md
Media pipeline The end-to-end media-file lifecycle: upload → master → derivatives → publication development/media_pipeline.md
Internationalization The two translation planes (data vs interface) and the language model development/internationalization.md
Tools (developer) Building tools and the full per-tool developer reference development/tools/reference/index.md
Services Shared services (e.g. upload) used by components, sections and tools development/services/index.md
Runtime One long-lived process, per-request isolation, and the operational consequences development/runtime_and_workers.md
Metrics The performance metrics subsystem and per-request monitor development/metrics.md
Media components Embedding Dédalo media components in third-party code development/using_media_components.md
CSS architecture The LESS-based design system and styling structure css-architecture.md
Installation Server sizing, the production guide, Docker, the dev quickstart, the reverse proxy, upgrading and troubleshooting install/index.md
Configuration The one config file (../private/.env): settings, database, areas, media/search tuning config/index.md
Management Environments, root user, maintenance status, recovery, hierarchies, updates management/index.md
Users & permissions Users, profiles, the 0–3 permission levels and how access is enforced management/users_and_permissions.md
Backup Backup procedure and best practices management/backup.md
Updates Updating code, data and ontology safely management/updates/index.md
Change log Release history and notable changes change_log.md

Upgrading from Dédalo v6

These two pages exist only for operators who already run a v6 install and are moving it to v7. They are the one place the previous engine's configuration files are named — because those files are the input you are converting. If you are installing Dédalo for the first time, you do not need them: go to Installation.

Page What
Migrating a v6 install to v7 The one migration manual: transform the data on v6, move the database and the media, convert the config, migrate the passwords, first v7 boot, and what to do when the data is wrong
What changed in v7 The v6 → v7 settings map: renamed, reshaped and removed