# nibinrj/buildlens architecture

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

- Interactive diagram: https://gitdiagram.com/nibinrj/buildlens
- Repository: https://github.com/nibinrj/buildlens

## Overview

BuildLens collects Jenkins build metadata, stage timings, test reports and log tails; its CLI streams them to an HTTP service, which validates and parses reports before transactional ingestion into PostgreSQL. The service also exposes build and health endpoints. Quarantine retrieval is advertised by the CLI but remains an unimplemented stub. The sampled source supports the main server and ingest connections; Jenkins shared-library internals and some runtime wiring are represented only where the CLI explicitly refers to them.

Main entry points: [`cmd/buildlens-server/main.go`](https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens-server/main.go) (HTTP server), [`internal/api/builds.go`](https://github.com/nibinrj/buildlens/blob/main/internal/api/builds.go) (Build API), [`cmd/buildlens/report.go`](https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens/report.go) (Report upload), [`internal/ingest/ingest.go`](https://github.com/nibinrj/buildlens/blob/main/internal/ingest/ingest.go) (Ingest service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Jenkins capture"]
  node_stage_capture["Stage timing<br/>[timedStage.groovy]"]
  node_build_report["Build reporting<br/>[reportBuild.groovy]"]
end

subgraph group_client["Upload client"]
  node_cli["BuildLens CLI<br/>[main.go]"]
  node_report_upload["Report upload<br/>[report.go]"]
  node_upload_format["Upload format<br/>[upload.go]"]
  node_quarantine["Quarantine command<br/>[main.go]"]
end

subgraph group_service["Ingest service"]
  node_http_server["HTTP server<br/>[main.go]"]
  node_build_api["Build API<br/>[builds.go]"]
  node_health_api["Health endpoint<br/>[health.go]"]
  node_surefire["Surefire parser<br/>[surefire.go]"]
  node_ingest["Ingest service<br/>[ingest.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_persistence["Persistence"]
  node_db_setup["Database setup<br/>[db.go]"]
  node_migrations["Schema migrations<br/>[embed.go]"]
  node_store["SQL store<br/>[ingest.sql.go]"]
  node_postgres[("PostgreSQL")]
end

node_jenkins(("Jenkins pipeline"))

node_jenkins -->|"runs"| node_cli
node_stage_capture -.->|"records stages"| node_build_report
node_build_report -->|"provides timings"| node_report_upload
node_cli -->|"dispatches report"| node_report_upload
node_report_upload -->|"encodes upload"| node_upload_format
node_report_upload -.->|"posts build"| node_http_server
node_http_server -->|"loads settings"| node_config
node_http_server -->|"opens database"| node_db_setup
node_http_server -.->|"registers routes"| node_build_api
node_http_server -.->|"serves health"| node_health_api
node_build_api -->|"validates parts"| node_upload_format
node_build_api -->|"parses reports"| node_surefire
node_build_api -->|"submits build"| node_ingest
node_ingest -->|"merges results"| node_surefire
node_ingest -->|"runs queries"| node_store
node_store -->|"executes SQL"| node_postgres
node_db_setup -->|"connects"| node_postgres
node_db_setup -->|"applies schema"| node_migrations

click node_stage_capture "https://github.com/nibinrj/buildlens/blob/main/shared-library/vars/timedStage.groovy"
click node_build_report "https://github.com/nibinrj/buildlens/blob/main/shared-library/vars/reportBuild.groovy"
click node_cli "https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens/main.go"
click node_report_upload "https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens/report.go"
click node_upload_format "https://github.com/nibinrj/buildlens/blob/main/internal/upload/upload.go"
click node_http_server "https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens-server/main.go"
click node_build_api "https://github.com/nibinrj/buildlens/blob/main/internal/api/builds.go"
click node_health_api "https://github.com/nibinrj/buildlens/blob/main/internal/api/health.go"
click node_surefire "https://github.com/nibinrj/buildlens/blob/main/internal/surefire/surefire.go"
click node_ingest "https://github.com/nibinrj/buildlens/blob/main/internal/ingest/ingest.go"
click node_config "https://github.com/nibinrj/buildlens/blob/main/internal/config/config.go"
click node_db_setup "https://github.com/nibinrj/buildlens/blob/main/internal/db/db.go"
click node_migrations "https://github.com/nibinrj/buildlens/blob/main/migrations/embed.go"
click node_store "https://github.com/nibinrj/buildlens/blob/main/internal/store/ingest.sql.go"
click node_quarantine "https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens/main.go"

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_stage_capture,node_build_report toneBlue
class node_cli,node_report_upload,node_upload_format,node_quarantine toneAmber
class node_http_server,node_build_api,node_health_api,node_surefire,node_ingest,node_config toneMint
class node_db_setup,node_migrations,node_store,node_postgres toneRose
class node_jenkins toneIndigo
```

## Components

### Jenkins capture

- [Stage timing](https://github.com/nibinrj/buildlens/blob/main/shared-library/vars/timedStage.groovy): `shared-library/vars/timedStage.groovy`
- [Build reporting](https://github.com/nibinrj/buildlens/blob/main/shared-library/vars/reportBuild.groovy): `shared-library/vars/reportBuild.groovy`

### Upload client

- [BuildLens CLI](https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens/main.go): `cmd/buildlens/main.go`
- [Report upload](https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens/report.go): `cmd/buildlens/report.go`
- [Upload format](https://github.com/nibinrj/buildlens/blob/main/internal/upload/upload.go): `internal/upload/upload.go`
- [Quarantine command](https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens/main.go): `cmd/buildlens/main.go`

### Ingest service

- [HTTP server](https://github.com/nibinrj/buildlens/blob/main/cmd/buildlens-server/main.go): `cmd/buildlens-server/main.go`
- [Build API](https://github.com/nibinrj/buildlens/blob/main/internal/api/builds.go): `internal/api/builds.go`
- [Health endpoint](https://github.com/nibinrj/buildlens/blob/main/internal/api/health.go): `internal/api/health.go`
- [Surefire parser](https://github.com/nibinrj/buildlens/blob/main/internal/surefire/surefire.go): `internal/surefire/surefire.go`
- [Ingest service](https://github.com/nibinrj/buildlens/blob/main/internal/ingest/ingest.go): `internal/ingest/ingest.go`
- [Configuration](https://github.com/nibinrj/buildlens/blob/main/internal/config/config.go): `internal/config/config.go`

### Persistence

- [Database setup](https://github.com/nibinrj/buildlens/blob/main/internal/db/db.go): `internal/db/db.go`
- [Schema migrations](https://github.com/nibinrj/buildlens/blob/main/migrations/embed.go): `migrations/embed.go`
- [SQL store](https://github.com/nibinrj/buildlens/blob/main/internal/store/ingest.sql.go): `internal/store/ingest.sql.go`
- **PostgreSQL**

### Other components

- **Jenkins pipeline**

## Connections

- Jenkins pipeline → BuildLens CLI: runs (evidence: `cmd/buildlens/main.go`)
- Stage timing → Build reporting: records stages
- Build reporting → Report upload: provides timings (evidence: `cmd/buildlens/report.go`)
- BuildLens CLI → Report upload: dispatches report (evidence: `cmd/buildlens/main.go`)
- Report upload → Upload format: encodes upload (evidence: `cmd/buildlens/report.go`)
- Report upload → HTTP server: posts build
- HTTP server → Configuration: loads settings (evidence: `cmd/buildlens-server/main.go`)
- HTTP server → Database setup: opens database (evidence: `cmd/buildlens-server/main.go`)
- HTTP server → Build API: registers routes
- HTTP server → Health endpoint: serves health
- Build API → Upload format: validates parts (evidence: `internal/api/builds.go`)
- Build API → Surefire parser: parses reports (evidence: `internal/api/builds.go`)
- Build API → Ingest service: submits build (evidence: `internal/api/builds.go`)
- Ingest service → Surefire parser: merges results (evidence: `internal/ingest/ingest.go`)
- Ingest service → SQL store: runs queries (evidence: `internal/ingest/ingest.go`)
- SQL store → PostgreSQL: executes SQL (evidence: `internal/store/ingest.sql.go`)
- Database setup → PostgreSQL: connects (evidence: `internal/db/db.go`)
- Database setup → Schema migrations: applies schema (evidence: `internal/db/db.go`)
