# apostolos00tapsas/vectorscan architecture

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

- Interactive diagram: https://gitdiagram.com/apostolos00tapsas/vectorscan
- Repository: https://github.com/apostolos00tapsas/vectorscan

## Overview

Vectorscan is a high-performance regular-expression matching library, compatible with the Hyperscan 5.4 API and designed to match many expressions across block, vectored, or streaming data. The main workflow is to compile expressions into a database, provide that database and input to a scan API, and receive match reports. Internally, compilation parses expressions, builds and optimizes graphs, then selects matching engines; runtime support includes database handling and scratch state. The README documents the product workflow and portability goals; source excerpts are limited, so some internal links are omitted.

Main entry points: [`src/compiler/compiler.cpp`](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/compiler/compiler.cpp) (Compiler orchestration), [`src/hs.h`](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/hs.h) (Scan API), [`src/hs_compile.h`](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/hs_compile.h) (Compile API), [`src/dispatcher.c`](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/dispatcher.c) (Runtime dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_compile_api["Compile API<br/>[hs_compile.h]"]
  node_scan_api["Scan API<br/>[hs.h]"]
  node_match_reports["Match reports<br/>[report.h]"]
end

subgraph group_compile["Compilation"]
  node_parser["Expression parser<br/>[Parser.h]"]
  node_graph_builder["Graph builder<br/>[ng_builder.cpp]"]
  node_graph_optimization["Graph optimization<br/>[ng.cpp]"]
  node_compiler["Compiler orchestration<br/>[compiler.cpp]"]
  node_report_manager["Report manager<br/>[report_manager.cpp]"]
end

subgraph group_engines["Matching engines"]
  node_literal_matcher["Literal matcher<br/>[hwlm.c]"]
  node_fdr_engine["FDR engine<br/>[fdr.c]"]
  node_nfa_engines["NFA engines<br/>[nfa_api_dispatch.c]"]
  node_rose["Rose matcher<br/>[match.c]"]
end

subgraph group_runtime["Scan runtime"]
  node_database[("Compiled database<br/>[database.c]")]
  node_dispatcher["Runtime dispatcher<br/>[dispatcher.c]"]
  node_scratch["Scratch state<br/>[scratch.c]"]
  node_stream_state["Stream state<br/>[stream.c]"]
end

node_caller(("Application"))

node_caller -->|"submits expressions"| node_compile_api
node_compile_api -->|"produces database"| node_database
node_caller -->|"provides input"| node_scan_api
node_scan_api -->|"uses database"| node_database
node_scan_api -->|"receives matches"| node_match_reports
node_compile_api -.->|"compiles patterns"| node_compiler
node_compiler -.->|"parses expressions"| node_parser
node_compiler -.->|"builds graphs"| node_graph_builder
node_graph_builder -.->|"optimizes graphs"| node_graph_optimization
node_compiler -->|"assigns reports"| node_report_manager
node_compiler -.->|"configures matching"| node_literal_matcher
node_compiler -.->|"selects engine"| node_fdr_engine
node_compiler -.->|"selects engine"| node_nfa_engines
node_compiler -.->|"builds matcher"| node_rose
node_scan_api -.->|"dispatches scans"| node_dispatcher
node_dispatcher -.->|"uses scratch"| node_scratch
node_dispatcher -.->|"maintains streams"| node_stream_state

click node_compile_api "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/hs_compile.h"
click node_scan_api "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/hs.h"
click node_match_reports "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/report.h"
click node_parser "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/parser/Parser.h"
click node_graph_builder "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/nfagraph/ng_builder.cpp"
click node_graph_optimization "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/nfagraph/ng.cpp"
click node_compiler "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/compiler/compiler.cpp"
click node_report_manager "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/util/report_manager.cpp"
click node_literal_matcher "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/hwlm/hwlm.c"
click node_fdr_engine "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/fdr/fdr.c"
click node_nfa_engines "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/nfa/nfa_api_dispatch.c"
click node_rose "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/rose/match.c"
click node_database "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/database.c"
click node_dispatcher "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/dispatcher.c"
click node_scratch "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/scratch.c"
click node_stream_state "https://github.com/apostolos00tapsas/vectorscan/blob/master/src/rose/stream.c"

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_compile_api,node_scan_api,node_match_reports toneBlue
class node_parser,node_graph_builder,node_graph_optimization,node_compiler,node_report_manager toneAmber
class node_literal_matcher,node_fdr_engine,node_nfa_engines,node_rose toneMint
class node_database,node_dispatcher,node_scratch,node_stream_state toneRose
class node_caller toneIndigo
```

## Components

### Public API

- [Compile API](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/hs_compile.h): `src/hs_compile.h`
- [Scan API](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/hs.h): `src/hs.h`
- [Match reports](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/report.h): `src/report.h`

### Compilation

- [Expression parser](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/parser/Parser.h): `src/parser/Parser.h`
- [Graph builder](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/nfagraph/ng_builder.cpp): `src/nfagraph/ng_builder.cpp`
- [Graph optimization](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/nfagraph/ng.cpp): `src/nfagraph/ng.cpp`
- [Compiler orchestration](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/compiler/compiler.cpp): `src/compiler/compiler.cpp`
- [Report manager](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/util/report_manager.cpp): `src/util/report_manager.cpp`

### Matching engines

- [Literal matcher](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/hwlm/hwlm.c): `src/hwlm/hwlm.c`
- [FDR engine](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/fdr/fdr.c): `src/fdr/fdr.c`
- [NFA engines](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/nfa/nfa_api_dispatch.c): `src/nfa/nfa_api_dispatch.c`
- [Rose matcher](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/rose/match.c): `src/rose/match.c`

### Scan runtime

- [Compiled database](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/database.c): `src/database.c`
- [Runtime dispatcher](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/dispatcher.c): `src/dispatcher.c`
- [Scratch state](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/scratch.c): `src/scratch.c`
- [Stream state](https://github.com/apostolos00tapsas/vectorscan/blob/master/src/rose/stream.c): `src/rose/stream.c`

### Other components

- **Application**

## Connections

- Application → Compile API: submits expressions
- Compile API → Compiled database: produces database (evidence: `src/hs_compile.h`)
- Application → Scan API: provides input
- Scan API → Compiled database: uses database
- Scan API → Match reports: receives matches
- Compile API → Compiler orchestration: compiles patterns
- Compiler orchestration → Expression parser: parses expressions
- Compiler orchestration → Graph builder: builds graphs
- Graph builder → Graph optimization: optimizes graphs
- Compiler orchestration → Report manager: assigns reports (evidence: `src/util/report_manager.cpp`)
- Compiler orchestration → Literal matcher: configures matching
- Compiler orchestration → FDR engine: selects engine
- Compiler orchestration → NFA engines: selects engine
- Compiler orchestration → Rose matcher: builds matcher
- Scan API → Runtime dispatcher: dispatches scans
- Runtime dispatcher → Scratch state: uses scratch
- Runtime dispatcher → Stream state: maintains streams
