# hrbrmstr/sergeant architecture

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

- Interactive diagram: https://gitdiagram.com/hrbrmstr/sergeant
- Repository: https://github.com/hrbrmstr/sergeant

## Overview

sergeant is an R client for querying and managing Apache Drill, with a DBI driver and dplyr interface over Drill’s REST API. The main workflow is to connect, build or submit a query, and receive results for use in R. The README also documents administrative and informational APIs, schema and storage inspection, custom SQL-function mappings, CTAS generation, and Docker helpers. Source excerpts were unavailable, so relationships below rely on README documentation; uncertain internal call wiring is omitted.

Main entry points: [`R/rest-api.r`](https://github.com/hrbrmstr/sergeant/blob/master/R/rest-api.r) (REST client), [`R/query.r`](https://github.com/hrbrmstr/sergeant/blob/master/R/query.r) (Query API), [`R/dplyr.r`](https://github.com/hrbrmstr/sergeant/blob/master/R/dplyr.r) (dplyr interface), [`R/dbi.r`](https://github.com/hrbrmstr/sergeant/blob/master/R/dbi.r) (DBI driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["R interfaces"]
  node_dplyr_interface["dplyr interface<br/>[dplyr.r]"]
  node_dbi_driver["DBI driver<br/>[dbi.r]"]
end

subgraph group_query["Query workflow"]
  node_query_api["Query API<br/>[query.r]"]
  node_result_conversion["Result conversion<br/>[query.r]"]
  node_rest_client["REST client<br/>[rest-api.r]"]
  node_custom_functions["SQL mappings<br/>[custom.r]"]
end

subgraph group_operations["Drill operations"]
  node_schema_inspection["Schema inspection<br/>[query.r]"]
  node_storage_inspection["Storage inspection<br/>[query.r]"]
  node_server_controls["Server controls<br/>[rest-api.r]"]
  node_query_profiles["Query profiles<br/>[rest-api.r]"]
end

subgraph group_helpers["Convenience helpers"]
  node_ctas["CTAS generation<br/>[ctas-profile.R]"]
  node_docker_helpers["Docker helpers<br/>[drill-docker.R]"]
end

node_r_user(("R user"))
node_drill_server["Apache Drill"]

node_r_user -->|"connects and queries"| node_dplyr_interface
node_dplyr_interface -->|"uses driver"| node_dbi_driver
node_dbi_driver -->|"uses REST"| node_rest_client
node_rest_client -->|"submits requests"| node_drill_server
node_r_user -->|"submits SQL"| node_query_api
node_query_api -->|"sends query"| node_rest_client
node_query_api -->|"converts results"| node_result_conversion
node_result_conversion -->|"returns data"| node_r_user
node_r_user -->|"uses mappings"| node_custom_functions
node_r_user -->|"generates statement"| node_ctas
node_r_user -->|"inspects schemas"| node_schema_inspection
node_schema_inspection -->|"requests metadata"| node_rest_client
node_r_user -->|"inspects storage"| node_storage_inspection
node_storage_inspection -->|"requests metadata"| node_rest_client
node_r_user -->|"manages server"| node_server_controls
node_server_controls -->|"sends controls"| node_rest_client
node_r_user -->|"inspects profiles"| node_query_profiles
node_query_profiles -->|"requests profiles"| node_rest_client
node_r_user -->|"manages Docker"| node_docker_helpers
node_docker_helpers -->|"starts or stops"| node_drill_server

click node_dplyr_interface "https://github.com/hrbrmstr/sergeant/blob/master/R/dplyr.r"
click node_dbi_driver "https://github.com/hrbrmstr/sergeant/blob/master/R/dbi.r"
click node_query_api "https://github.com/hrbrmstr/sergeant/blob/master/R/query.r"
click node_result_conversion "https://github.com/hrbrmstr/sergeant/blob/master/R/query.r"
click node_rest_client "https://github.com/hrbrmstr/sergeant/blob/master/R/rest-api.r"
click node_custom_functions "https://github.com/hrbrmstr/sergeant/blob/master/R/custom.r"
click node_ctas "https://github.com/hrbrmstr/sergeant/blob/master/R/ctas-profile.R"
click node_schema_inspection "https://github.com/hrbrmstr/sergeant/blob/master/R/query.r"
click node_storage_inspection "https://github.com/hrbrmstr/sergeant/blob/master/R/query.r"
click node_server_controls "https://github.com/hrbrmstr/sergeant/blob/master/R/rest-api.r"
click node_query_profiles "https://github.com/hrbrmstr/sergeant/blob/master/R/rest-api.r"
click node_docker_helpers "https://github.com/hrbrmstr/sergeant/blob/master/R/drill-docker.R"

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_dplyr_interface,node_dbi_driver,node_r_user toneBlue
class node_query_api,node_result_conversion,node_rest_client,node_custom_functions toneAmber
class node_schema_inspection,node_storage_inspection,node_server_controls,node_query_profiles toneMint
class node_ctas,node_docker_helpers toneRose
class node_drill_server toneIndigo
```

## Components

### R interfaces

- [dplyr interface](https://github.com/hrbrmstr/sergeant/blob/master/R/dplyr.r): `R/dplyr.r`
- [DBI driver](https://github.com/hrbrmstr/sergeant/blob/master/R/dbi.r): `R/dbi.r`

### Query workflow

- [Query API](https://github.com/hrbrmstr/sergeant/blob/master/R/query.r): `R/query.r`
- [Result conversion](https://github.com/hrbrmstr/sergeant/blob/master/R/query.r): `R/query.r`
- [REST client](https://github.com/hrbrmstr/sergeant/blob/master/R/rest-api.r): `R/rest-api.r`
- [SQL mappings](https://github.com/hrbrmstr/sergeant/blob/master/R/custom.r): `R/custom.r`

### Drill operations

- [Schema inspection](https://github.com/hrbrmstr/sergeant/blob/master/R/query.r): `R/query.r`
- [Storage inspection](https://github.com/hrbrmstr/sergeant/blob/master/R/query.r): `R/query.r`
- [Server controls](https://github.com/hrbrmstr/sergeant/blob/master/R/rest-api.r): `R/rest-api.r`
- [Query profiles](https://github.com/hrbrmstr/sergeant/blob/master/R/rest-api.r): `R/rest-api.r`

### Convenience helpers

- [CTAS generation](https://github.com/hrbrmstr/sergeant/blob/master/R/ctas-profile.R): `R/ctas-profile.R`
- [Docker helpers](https://github.com/hrbrmstr/sergeant/blob/master/R/drill-docker.R): `R/drill-docker.R`

### Other components

- **R user**
- **Apache Drill**

## Connections

- R user → dplyr interface: connects and queries
- dplyr interface → DBI driver: uses driver
- DBI driver → REST client: uses REST
- REST client → Apache Drill: submits requests
- R user → Query API: submits SQL
- Query API → REST client: sends query
- Query API → Result conversion: converts results
- Result conversion → R user: returns data
- R user → SQL mappings: uses mappings
- R user → CTAS generation: generates statement
- R user → Schema inspection: inspects schemas
- Schema inspection → REST client: requests metadata
- R user → Storage inspection: inspects storage
- Storage inspection → REST client: requests metadata
- R user → Server controls: manages server
- Server controls → REST client: sends controls
- R user → Query profiles: inspects profiles
- Query profiles → REST client: requests profiles
- R user → Docker helpers: manages Docker
- Docker helpers → Apache Drill: starts or stops