# thomasheckmann/zxinfo-api-v5 architecture

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

- Interactive diagram: https://gitdiagram.com/thomasheckmann/zxinfo-api-v5
- Repository: https://github.com/thomasheckmann/zxinfo-api-v5

## Overview

ZXInfo API v5 exposes ZXDB search and lookup capabilities over HTTP, backed by Elasticsearch. The main request path is client → Express app → versioned routes → feature handler → search/helper or Elasticsearch → response. The repository also contains legacy search-index generators and import scripts for building/populating the search index; their internal wiring is not shown in the excerpts, so those relationships are left unasserted.

Main entry points: [`v5/routes.js`](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/routes.js) (API routes), [`v5/common/elastic.js`](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/common/elastic.js) (Elasticsearch client), [`v5/entries/entries.js`](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/entries/entries.js) (Entry lookup), [`v5/search/search.js`](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/search/search.js) (Text search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API routing"]
  node_app["Express app<br/>[app.js]"]
  node_routes["API routes<br/>[routes.js]"]
end

subgraph group_features["ZXDB features"]
  node_entries["Entry lookup<br/>[entries.js]"]
  node_filecheck["File check<br/>[filecheck.js]"]
  node_filesearch["File search<br/>[filesearch.js]"]
  node_search["Text search<br/>[search.js]"]
  node_suggest["Suggestions<br/>[suggest.js]"]
  node_typeahead["Typeahead<br/>[typeahead.js]"]
end

subgraph group_shared["Search infrastructure"]
  node_queryterms["Query builders<br/>[queryTerms.js]"]
  node_searchhelper["Search executor<br/>[helpersSearch.js]"]
  node_requesthelper["Request defaults<br/>[helpersRequest.js]"]
  node_utils["Output utilities<br/>[utils.js]"]
  node_elasticclient["Elasticsearch client<br/>[elastic.js]"]
end

subgraph group_indexing["Index preparation"]
  node_indexconfig["MariaDB connection<br/>[dbConfig.js]"]
  node_indexmain["Index generator<br/>[index.js]"]
  node_indexv1["Index generator v1<br/>[index-v1.js]"]
  node_indexdebug["Debug indexer<br/>[index-debug.js]"]
  node_imports["ZXDB import scripts"]
end

node_client(("API client"))
node_elasticsearch[("Elasticsearch")]
node_mariadb[("MariaDB")]

node_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_routes
node_routes -->|"routes requests"| node_entries
node_routes -->|"routes requests"| node_filecheck
node_routes -->|"routes requests"| node_filesearch
node_routes -->|"routes requests"| node_search
node_routes -->|"routes requests"| node_suggest
node_routes -->|"routes requests"| node_typeahead
node_search -->|"builds queries"| node_queryterms
node_entries -->|"builds filters"| node_queryterms
node_search -->|"executes search"| node_searchhelper
node_entries -->|"executes search"| node_searchhelper
node_searchhelper -->|"queries"| node_elasticclient
node_entries -->|"queries"| node_elasticclient
node_filesearch -->|"searches and looks up"| node_elasticclient
node_filecheck -->|"checks records"| node_elasticclient
node_suggest -->|"queries suggestions"| node_elasticclient
node_typeahead -->|"queries completions"| node_elasticclient
node_elasticclient -->|"sends queries"| node_elasticsearch
node_searchhelper -->|"formats results"| node_utils
node_search -->|"sorts results"| node_utils
node_entries -->|"formats entries"| node_utils
node_filesearch -->|"uses fallback"| node_requesthelper
node_indexmain -->|"uses connection"| node_indexconfig
node_indexv1 -->|"uses connection"| node_indexconfig
node_indexdebug -->|"uses connection"| node_indexconfig
node_indexconfig -->|"connects to"| node_mariadb
node_imports -.->|"populates index"| node_elasticsearch

click node_app "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/app.js"
click node_routes "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/routes.js"
click node_entries "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/entries/entries.js"
click node_filecheck "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/filecheck/filecheck.js"
click node_filesearch "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/filesearch/filesearch.js"
click node_search "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/search/search.js"
click node_suggest "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/suggest/suggest.js"
click node_typeahead "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/typeahead/typeahead.js"
click node_queryterms "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/search/queryTerms.js"
click node_searchhelper "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/search/helpersSearch.js"
click node_requesthelper "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/common/helpersRequest.js"
click node_utils "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/common/utils.js"
click node_elasticclient "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/common/elastic.js"
click node_indexconfig "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/search-index/dbConfig.js"
click node_indexmain "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/search-index/index.js"
click node_indexv1 "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/search-index/index-v1.js"
click node_indexdebug "https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/search-index/index-debug.js"
click node_imports "https://github.com/thomasheckmann/zxinfo-api-v5/tree/main/es-import"

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_app,node_routes,node_client toneBlue
class node_entries,node_filecheck,node_filesearch,node_search,node_suggest,node_typeahead,node_elasticsearch,node_mariadb toneAmber
class node_queryterms,node_searchhelper,node_requesthelper,node_utils,node_elasticclient toneMint
class node_indexconfig,node_indexmain,node_indexv1,node_indexdebug,node_imports toneRose
```

## Components

### API routing

- [Express app](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/app.js): `app.js`
- [API routes](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/routes.js): `v5/routes.js`

### ZXDB features

- [Entry lookup](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/entries/entries.js): `v5/entries/entries.js`
- [File check](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/filecheck/filecheck.js): `v5/filecheck/filecheck.js`
- [File search](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/filesearch/filesearch.js): `v5/filesearch/filesearch.js`
- [Text search](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/search/search.js): `v5/search/search.js`
- [Suggestions](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/suggest/suggest.js): `v5/suggest/suggest.js`
- [Typeahead](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/typeahead/typeahead.js): `v5/typeahead/typeahead.js`

### Search infrastructure

- [Query builders](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/search/queryTerms.js): `v5/search/queryTerms.js`
- [Search executor](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/search/helpersSearch.js): `v5/search/helpersSearch.js`
- [Request defaults](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/common/helpersRequest.js): `v5/common/helpersRequest.js`
- [Output utilities](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/common/utils.js): `v5/common/utils.js`
- [Elasticsearch client](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/v5/common/elastic.js): `v5/common/elastic.js`

### Index preparation

- [MariaDB connection](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/search-index/dbConfig.js): `search-index/dbConfig.js`
- [Index generator](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/search-index/index.js): `search-index/index.js`
- [Index generator v1](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/search-index/index-v1.js): `search-index/index-v1.js`
- [Debug indexer](https://github.com/thomasheckmann/zxinfo-api-v5/blob/main/search-index/index-debug.js): `search-index/index-debug.js`
- [ZXDB import scripts](https://github.com/thomasheckmann/zxinfo-api-v5/tree/main/es-import): `es-import`

### Other components

- **API client**
- **Elasticsearch**
- **MariaDB**

## Connections

- API client → Express app: sends requests (evidence: `README.md`)
- Express app → API routes: mounts routes (evidence: `app.js`)
- API routes → Entry lookup: routes requests (evidence: `v5/routes.js`)
- API routes → File check: routes requests (evidence: `v5/routes.js`)
- API routes → File search: routes requests (evidence: `v5/routes.js`)
- API routes → Text search: routes requests (evidence: `v5/routes.js`)
- API routes → Suggestions: routes requests (evidence: `v5/routes.js`)
- API routes → Typeahead: routes requests (evidence: `v5/routes.js`)
- Text search → Query builders: builds queries (evidence: `v5/search/search.js`)
- Entry lookup → Query builders: builds filters (evidence: `v5/entries/entries.js`)
- Text search → Search executor: executes search (evidence: `v5/search/search.js`)
- Entry lookup → Search executor: executes search (evidence: `v5/entries/entries.js`)
- Search executor → Elasticsearch client: queries (evidence: `v5/search/helpersSearch.js`)
- Entry lookup → Elasticsearch client: queries (evidence: `v5/entries/entries.js`)
- File search → Elasticsearch client: searches and looks up (evidence: `v5/filesearch/filesearch.js`)
- File check → Elasticsearch client: checks records (evidence: `v5/filecheck/filecheck.js`)
- Suggestions → Elasticsearch client: queries suggestions (evidence: `v5/suggest/suggest.js`)
- Typeahead → Elasticsearch client: queries completions (evidence: `v5/typeahead/typeahead.js`)
- Elasticsearch client → Elasticsearch: sends queries (evidence: `v5/common/elastic.js`)
- Search executor → Output utilities: formats results (evidence: `v5/search/helpersSearch.js`)
- Text search → Output utilities: sorts results (evidence: `v5/search/search.js`)
- Entry lookup → Output utilities: formats entries (evidence: `v5/entries/entries.js`)
- File search → Request defaults: uses fallback (evidence: `v5/filesearch/filesearch.js`)
- Index generator → MariaDB connection: uses connection (evidence: `search-index/index.js`)
- Index generator v1 → MariaDB connection: uses connection (evidence: `search-index/index-v1.js`)
- Debug indexer → MariaDB connection: uses connection (evidence: `search-index/index-debug.js`)
- MariaDB connection → MariaDB: connects to (evidence: `search-index/dbConfig.js`)
- ZXDB import scripts → Elasticsearch: populates index (evidence: `README.md`)
