# trailofbits/trailmark architecture

> Architecture diagram of the GitHub repository trailofbits/trailmark, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trailofbits/trailmark
- Repository: https://github.com/trailofbits/trailmark
- Video tour (about a minute): https://gitdiagram.com/trailofbits/trailmark/video

## Overview

Trailmark parses source code into a graph of code units, relationships, and annotations, indexes that graph for traversal, then exposes queries and exports for security analysis. The README documents language coverage and analysis features; sampled parser excerpts confirm AST extraction, while the exact wiring of several unsampled orchestration and analysis modules is not established, so those links are omitted.

Main entry points: [`src/trailmark/query/api.py`](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/query/api.py) (QueryEngine), [`src/trailmark/models/graph.py`](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/models/graph.py) (CodeGraph model), [`src/trailmark/parsers`](https://github.com/trailofbits/trailmark/tree/main/src/trailmark/parsers) (Language parsers), [`src/trailmark/cli.py`](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Source parsing"]
  node_parse["Parse orchestration<br/>[parse.py]"]
  node_parsers["Language parsers"]
  node_custom["Custom grammars"]
end

subgraph group_graph["Graph model and index"]
  node_model["CodeGraph model<br/>[graph.py]"]
  node_nodes["Code units<br/>[nodes.py]"]
  node_edges["Code edges<br/>[edges.py]"]
  node_annotations["Annotations<br/>[annotations.py]"]
  node_store[("GraphStore<br/>[graph_store.py]")]
end

subgraph group_analysis["Security analysis"]
  node_preanalysis["Pre-analysis<br/>[preanalysis.py]"]
  node_entrypoints["Entrypoints<br/>[entrypoints.py]"]
  node_augment["Finding augmentation<br/>[augment.py]"]
  node_binary["Binary augmentation<br/>[binary.py]"]
  node_diff["Graph diff<br/>[diff.py]"]
end

subgraph group_interface["User interface"]
  node_cli["CLI<br/>[cli.py]"]
  node_query["QueryEngine<br/>[api.py]"]
  node_diagram["Diagram output<br/>[diagram.py]"]
end

node_source["Source files"]
node_user(("Engineer"))
node_results["JSON / summaries"]

node_user -->|"runs"| node_cli
node_source -->|"provides files"| node_parse
node_cli -->|"invokes"| node_parse
node_parse -->|"dispatches parsing"| node_parsers
node_parsers -.->|"uses grammar"| node_custom
node_parsers -->|"builds graph"| node_model
node_model -->|"stores units"| node_nodes
node_model -->|"stores relations"| node_edges
node_model -->|"stores annotations"| node_annotations
node_model -->|"loads graph"| node_store
node_query -->|"traverses index"| node_store
node_query -->|"runs passes"| node_preanalysis
node_query -->|"detects entrypoints"| node_entrypoints
node_query -->|"merges findings"| node_augment
node_query -->|"merges binary graph"| node_binary
node_query -->|"compares graphs"| node_diff
node_query -->|"renders graph"| node_diagram
node_cli -->|"queries graph"| node_query
node_query -->|"exports results"| node_results

click node_cli "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/cli.py"
click node_parse "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/parse.py"
click node_parsers "https://github.com/trailofbits/trailmark/tree/main/src/trailmark/parsers"
click node_custom "https://github.com/trailofbits/trailmark/tree/main/src/trailmark/tree_sitter_custom"
click node_model "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/models/graph.py"
click node_nodes "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/models/nodes.py"
click node_edges "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/models/edges.py"
click node_annotations "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/models/annotations.py"
click node_store "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/storage/graph_store.py"
click node_query "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/query/api.py"
click node_preanalysis "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/preanalysis.py"
click node_entrypoints "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/entrypoints.py"
click node_augment "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/augment.py"
click node_binary "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/binary.py"
click node_diff "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/diff.py"
click node_diagram "https://github.com/trailofbits/trailmark/blob/main/src/trailmark/diagram.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parse,node_parsers,node_custom toneBlue
class node_model,node_nodes,node_edges,node_annotations,node_store toneAmber
class node_preanalysis,node_entrypoints,node_augment,node_binary,node_diff toneMint
class node_cli,node_query,node_diagram toneRose
class node_source,node_user,node_results toneIndigo
```

## Components

### Source parsing

- [Parse orchestration](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/parse.py): `src/trailmark/parse.py`
- [Language parsers](https://github.com/trailofbits/trailmark/tree/main/src/trailmark/parsers): `src/trailmark/parsers`
- [Custom grammars](https://github.com/trailofbits/trailmark/tree/main/src/trailmark/tree_sitter_custom): `src/trailmark/tree_sitter_custom`

### Graph model and index

- [CodeGraph model](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/models/graph.py): `src/trailmark/models/graph.py`
- [Code units](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/models/nodes.py): `src/trailmark/models/nodes.py`
- [Code edges](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/models/edges.py): `src/trailmark/models/edges.py`
- [Annotations](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/models/annotations.py): `src/trailmark/models/annotations.py`
- [GraphStore](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/storage/graph_store.py): `src/trailmark/storage/graph_store.py`

### Security analysis

- [Pre-analysis](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/preanalysis.py): `src/trailmark/analysis/preanalysis.py`
- [Entrypoints](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/entrypoints.py): `src/trailmark/analysis/entrypoints.py`
- [Finding augmentation](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/augment.py): `src/trailmark/analysis/augment.py`
- [Binary augmentation](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/binary.py): `src/trailmark/analysis/binary.py`
- [Graph diff](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/analysis/diff.py): `src/trailmark/analysis/diff.py`

### User interface

- [CLI](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/cli.py): `src/trailmark/cli.py`
- [QueryEngine](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/query/api.py): `src/trailmark/query/api.py`
- [Diagram output](https://github.com/trailofbits/trailmark/blob/main/src/trailmark/diagram.py): `src/trailmark/diagram.py`

### Other components

- **Source files**
- **Engineer**
- **JSON / summaries**

## Connections

- Engineer → CLI: runs
- Source files → Parse orchestration: provides files
- CLI → Parse orchestration: invokes
- Parse orchestration → Language parsers: dispatches parsing
- Language parsers → Custom grammars: uses grammar
- Language parsers → CodeGraph model: builds graph
- CodeGraph model → Code units: stores units
- CodeGraph model → Code edges: stores relations
- CodeGraph model → Annotations: stores annotations
- CodeGraph model → GraphStore: loads graph
- QueryEngine → GraphStore: traverses index
- QueryEngine → Pre-analysis: runs passes
- QueryEngine → Entrypoints: detects entrypoints
- QueryEngine → Finding augmentation: merges findings
- QueryEngine → Binary augmentation: merges binary graph
- QueryEngine → Graph diff: compares graphs
- QueryEngine → Diagram output: renders graph
- CLI → QueryEngine: queries graph
- QueryEngine → JSON / summaries: exports results