Deriva
0.8.8 · out now

Deriva

From code repositories to ArchiMate models

Deriva reads a software repository, builds a graph of what is in it, and derives an ArchiMate enterprise architecture model you can open in Archi.

Get started View on GitHub
The Deriva mark Contour lines that are messy at the edge and grow calmer inward, closing in a perfect core: the repository at the edge, then the intermediate graph and the output graph, and the ArchiMate model at the core.

How it works

From mess to structure

Deriva brings determinism to AI-assisted architecture model derivation. Parsing and graph algorithms find the structure; an LLM reads what needs reading. Every prompt is versioned configuration you can open and change.

  1. 01 · clone

    Repository

    The code as it is: a Git repository, cloned locally. Deriva classifies every file by type, from source and config to docs, tests and build files.

    cloneclassify
  2. 02 · extract

    Intermediate graph

    Parsing turns the code into a graph of files, types, methods, dependencies, technologies and business concepts. Graph metrics then rank what matters.

    parsePageRankLouvaink-core
  3. 03 · derive

    Output graph

    Graph structure decides the elements and most of their names, and only relationships the ArchiMate 3.2 metamodel allows are drawn. An LLM makes the few closed choices structure cannot, each asked once, then refine steps tidy the result. In the studio, each element links back to the graph nodes it came from.

    generaterefine
  4. 04 · export

    ArchiMate model

    The output graph exports as an ArchiMate model in the Open Group exchange format, ready to open in Archi.

    exportArchi

Deriva Studio

Watch the model take shape

A local web app for the whole pipeline. Run a repository and watch it unfold on one canvas: the intermediate graph grows step by step, and each derived element links back to the nodes it came from. Follow every step and prompt live, read the model at the enterprise or solution level, and edit the settings as new versions.

Deriva Studio's Workspace in the dark theme after a full run on the Deriva repository: one canvas with the repository, a sample of the intermediate graph, the output graph grouped into business, application and technology layers, and the model, linked from left to right; the run's live log below ends with Run finished Deriva Studio's Workspace in the light theme after a full run on the Deriva repository: one canvas with the repository, a sample of the intermediate graph, the output graph grouped into business, application and technology layers, and the model, linked from left to right; the run's live log below ends with Run finished
The Workspace after a full run on Deriva's own repository: the repository, a sample of the intermediate graph (its modules, classes and methods), the output graph by ArchiMate layer and the model, with links from each derived element back to the graph nodes it came from.
Deriva Studio's output model in the dark theme: LakesideMutual at the enterprise level in the Layered view, with business, application and technology layers, a Quality: ok pill, the selected element Customer Core and, below, the trace of the deployable unit it was derived from Deriva Studio's output model in the light theme: LakesideMutual at the enterprise level in the Layered view, with business, application and technology layers, a Quality: ok pill, the selected element Customer Core and, below, the trace of the deployable unit it was derived from
Read the model at two levels. LakesideMutual, a public sample application, at the enterprise level in the Layered view; Solution and Detail show the components, modules and interfaces below it. The Quality pill judges the model from its structure, and the Trace tab shows where the selected element came from.
Deriva Studio's Repositories page in the dark theme: the Deriva repository selected, with its commit, the nodes and edges of its graph database, its model's elements and relationships, its last runs, and a Coverage section reporting 574 of 574 files in the graph with a table per file extension Deriva Studio's Repositories page in the light theme: the Deriva repository selected, with its commit, the nodes and edges of its graph database, its model's elements and relationships, its last runs, and a Coverage section reporting 574 of 574 files in the graph with a table per file extension
Know what went in. The Repositories page shows what each repository's graph database holds and its last runs. Coverage compares the checkout with the graph: all 574 files of Deriva's repository reached it, and per file type it shows which step reads them.
Deriva Studio's intermediate ontology in the dark theme: the node types of the extraction graph drawn as a graph, sized by count and coloured by group, with File selected so its neighbours and edge types are named; a panel on the right lists the step that produces File, the derivation steps that read it, its eight edges and its properties Deriva Studio's intermediate ontology in the light theme: the node types of the extraction graph drawn as a graph, sized by count and coloured by group, with File selected so its neighbours and edge types are named; a panel on the right lists the step that produces File, the derivation steps that read it, its eight edges and its properties
See what extraction builds. The intermediate ontology as a graph: every node type of the graph, sized by its count and coloured by group, with arrows for the edge types between them. Select a type, here File, for the extraction step that produces it, the derivation steps that read it, its edges and its properties.
Deriva Studio's derivation configuration in the dark theme: the derivation steps by phase with their versions and switches on the left, and the ApplicationComponent step at version 2 on the right with its History tab open, version 1 selected, the change to its example shown as a diff and a Use this version button Deriva Studio's derivation configuration in the light theme: the derivation steps by phase with their versions and switches on the left, and the ApplicationComponent step at version 2 on the right with its History tab open, version 1 selected, the change to its example shown as a diff and a Use this version button
Every prompt is versioned. Each derivation step keeps its instruction, example, candidate query and parameters as versioned configuration. The History tab shows what changed, here ApplicationComponent from version 2 back to version 1, and Use this version restores an earlier one. Changed texts are checked for overfitting before they are saved.
Deriva Studio's benchmark inspector in the dark theme: three runs of the same model on LakesideMutual, matched by source and grouped by cause; at the top one business actor, Client, present in only one of three runs and marked as not a candidate in the other two, and below it 67 stable elements marked 3/3; a results table at the bottom scores consistency by name and by source Deriva Studio's benchmark inspector in the light theme: three runs of the same model on LakesideMutual, matched by source and grouped by cause; at the top one business actor, Client, present in only one of three runs and marked as not a candidate in the other two, and below it 67 stable elements marked 3/3; a results table at the bottom scores consistency by name and by source
Compare runs. Three runs of the same model on LakesideMutual, matched by source: all but one element came out the same in every run. The one that differs, a business actor that only one run produced, is marked with the runs it is missing from and why. The table below scores consistency per repository, by name and by source.

Get started

Run it on your machine

Deriva runs locally: the studio in your browser, the pipeline and its databases on your machine. You bring the LLM, a cloud API key or a local model.

  • Python 3.14 and uv (uv downloads Python for you)
  • Git, to clone the repositories you analyse
  • An LLM: Azure OpenAI, OpenAI, Anthropic or Mistral, or local with Ollama or LM Studio

Installation guide and how-tos

  1. Install Deriva

    uv tool install --python 3.14 deriva-studio

    Deriva ships as three packages on PyPI: deriva-studio (the studio and the command line), deriva-cli (the command line only) and deriva-dev (both, plus benchmarking). To try it without installing: uvx --python 3.14 deriva-studio.

  2. Start it (opens on http://127.0.0.1:8765)

    deriva

    Deriva keeps its settings and data in ~/.deriva. On first start a banner points to General, where you add an LLM model.

Research

A research project

Deriva is part of a research project on AI-assisted domain modeling. It is evaluated on held-out repositories; results follow with the final benchmark. The code is open source under the AGPL-3.0.

* dērīvāre/deːriːˈwaːre/— Latin: to draw off, to obtain, to derive