# kitagry/bqls architecture

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

- Interactive diagram: https://gitdiagram.com/kitagry/bqls
- Repository: https://github.com/kitagry/bqls

## Overview

bqls is a BigQuery language server: an editor sends SQL documents and requests over LSP, and the server provides SQL-aware editing features or runs BigQuery commands and returns results/previews. The VS Code extension is an optional editor-facing integration. The graph captures documented capabilities, but some subsystem wiring is inferred only from names and README descriptions; uncertain call edges are omitted.

Main entry points: [`langserver/langserver.go`](https://github.com/kitagry/bqls/blob/main/langserver/langserver.go) (LSP handler), [`langserver/internal/source/project.go`](https://github.com/kitagry/bqls/blob/main/langserver/internal/source/project.go) (Project services), [`langserver/execute_command.go`](https://github.com/kitagry/bqls/blob/main/langserver/execute_command.go) (Workspace commands), [`editors/vscode/src/extension.ts`](https://github.com/kitagry/bqls/blob/main/editors/vscode/src/extension.ts) (VS Code extension)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Editor clients"]
  node_vscode["VS Code extension<br/>[extension.ts]"]
  node_vscode_commands["Command UI"]
end

subgraph group_protocol["LSP server"]
  node_server_entry["Server process<br/>[main.go]"]
  node_handler["LSP handler<br/>[langserver.go]"]
  node_initialize["Initialization<br/>[initialize.go]"]
  node_text_document["Document events<br/>[text_document.go]"]
  node_completion["Completion<br/>[completion.go]"]
  node_diagnostics["Diagnostics<br/>[diagnostic.go]"]
  node_formatting["Formatting<br/>[format.go]"]
  node_hover["Hover details<br/>[hover.go]"]
  node_definition["Definition lookup<br/>[definition.go]"]
  node_commands["Workspace commands<br/>[execute_command.go]"]
  node_virtual_docs["Virtual documents"]
  node_results["Result export<br/>[execute_command.go]"]
end

subgraph group_sql["SQL intelligence"]
  node_project["Project services<br/>[project.go]"]
  node_analysis["SQL analysis<br/>[analyze.go]"]
  node_sql_parser["SQL parser<br/>[parser.go]"]
  node_completion_engine["Completion engine<br/>[completion.go]"]
  node_document_info["Document intelligence<br/>[document.go]"]
end

subgraph group_cloud["BigQuery services"]
  node_bq_client["BigQuery client<br/>[bigquery.go]"]
end

node_editor_user(("SQL author"))
node_bq_service[("BigQuery")]
node_google_sheets[("Google Sheets")]

node_editor_user -->|"edits SQL"| node_vscode
node_editor_user -->|"uses LSP client"| node_server_entry
node_vscode -->|"starts server"| node_server_entry
node_vscode -->|"handles results"| node_vscode_commands
node_server_entry -->|"creates handler"| node_handler
node_handler -->|"dispatches"| node_initialize
node_handler -->|"dispatches"| node_text_document
node_handler -->|"dispatches"| node_completion
node_handler -->|"dispatches"| node_diagnostics
node_handler -->|"dispatches"| node_formatting
node_handler -->|"dispatches"| node_hover
node_handler -->|"dispatches"| node_definition
node_handler -->|"dispatches"| node_commands
node_handler -->|"dispatches"| node_virtual_docs
node_completion -->|"requests completion"| node_project
node_completion -->|"builds suggestions"| node_completion_engine
node_diagnostics -->|"requests analysis"| node_project
node_formatting -->|"formats document"| node_project
node_hover -->|"requests details"| node_project
node_definition -->|"resolves symbol"| node_project
node_text_document -->|"updates documents"| node_project
node_project -->|"analyzes SQL"| node_analysis
node_analysis -->|"parses SQL"| node_sql_parser
node_project -->|"provides context"| node_document_info
node_commands -->|"runs query"| node_project
node_commands -->|"lists jobs and data"| node_bq_client
node_project -->|"fetches metadata"| node_bq_client
node_bq_client -->|"queries BigQuery"| node_bq_service
node_virtual_docs -->|"builds previews"| node_project
node_commands -->|"exports rows"| node_results
node_results -.->|"writes spreadsheets"| node_google_sheets
node_commands -->|"returns command results"| node_vscode_commands

click node_vscode "https://github.com/kitagry/bqls/blob/main/editors/vscode/src/extension.ts"
click node_vscode_commands "https://github.com/kitagry/bqls/blob/main/editors/vscode/src/commandResultHandler.ts"
click node_server_entry "https://github.com/kitagry/bqls/blob/main/main.go"
click node_handler "https://github.com/kitagry/bqls/blob/main/langserver/langserver.go"
click node_initialize "https://github.com/kitagry/bqls/blob/main/langserver/initialize.go"
click node_text_document "https://github.com/kitagry/bqls/blob/main/langserver/text_document.go"
click node_completion "https://github.com/kitagry/bqls/blob/main/langserver/completion.go"
click node_diagnostics "https://github.com/kitagry/bqls/blob/main/langserver/diagnostic.go"
click node_formatting "https://github.com/kitagry/bqls/blob/main/langserver/format.go"
click node_hover "https://github.com/kitagry/bqls/blob/main/langserver/hover.go"
click node_definition "https://github.com/kitagry/bqls/blob/main/langserver/definition.go"
click node_commands "https://github.com/kitagry/bqls/blob/main/langserver/execute_command.go"
click node_virtual_docs "https://github.com/kitagry/bqls/blob/main/langserver/virtual_text_document.go"
click node_project "https://github.com/kitagry/bqls/blob/main/langserver/internal/source/project.go"
click node_analysis "https://github.com/kitagry/bqls/blob/main/langserver/internal/source/file/analyze.go"
click node_sql_parser "https://github.com/kitagry/bqls/blob/main/langserver/internal/source/bqparser/parser.go"
click node_completion_engine "https://github.com/kitagry/bqls/blob/main/langserver/internal/source/completion/completion.go"
click node_document_info "https://github.com/kitagry/bqls/blob/main/langserver/internal/source/document.go"
click node_bq_client "https://github.com/kitagry/bqls/blob/main/langserver/internal/bigquery/bigquery.go"
click node_results "https://github.com/kitagry/bqls/blob/main/langserver/execute_command.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_vscode,node_vscode_commands toneBlue
class node_server_entry,node_handler,node_initialize,node_text_document,node_completion,node_diagnostics,node_formatting,node_hover,node_definition,node_commands,node_virtual_docs,node_results,node_bq_service,node_google_sheets toneAmber
class node_project,node_analysis,node_sql_parser,node_completion_engine,node_document_info toneMint
class node_bq_client toneRose
class node_editor_user toneIndigo
```

## Components

### Editor clients

- [VS Code extension](https://github.com/kitagry/bqls/blob/main/editors/vscode/src/extension.ts): `editors/vscode/src/extension.ts`
- [Command UI](https://github.com/kitagry/bqls/blob/main/editors/vscode/src/commandResultHandler.ts): `editors/vscode/src/commandResultHandler.ts`

### LSP server

- [Server process](https://github.com/kitagry/bqls/blob/main/main.go): `main.go`
- [LSP handler](https://github.com/kitagry/bqls/blob/main/langserver/langserver.go): `langserver/langserver.go`
- [Initialization](https://github.com/kitagry/bqls/blob/main/langserver/initialize.go): `langserver/initialize.go`
- [Document events](https://github.com/kitagry/bqls/blob/main/langserver/text_document.go): `langserver/text_document.go`
- [Completion](https://github.com/kitagry/bqls/blob/main/langserver/completion.go): `langserver/completion.go`
- [Diagnostics](https://github.com/kitagry/bqls/blob/main/langserver/diagnostic.go): `langserver/diagnostic.go`
- [Formatting](https://github.com/kitagry/bqls/blob/main/langserver/format.go): `langserver/format.go`
- [Hover details](https://github.com/kitagry/bqls/blob/main/langserver/hover.go): `langserver/hover.go`
- [Definition lookup](https://github.com/kitagry/bqls/blob/main/langserver/definition.go): `langserver/definition.go`
- [Workspace commands](https://github.com/kitagry/bqls/blob/main/langserver/execute_command.go): `langserver/execute_command.go`
- [Virtual documents](https://github.com/kitagry/bqls/blob/main/langserver/virtual_text_document.go): `langserver/virtual_text_document.go`
- [Result export](https://github.com/kitagry/bqls/blob/main/langserver/execute_command.go): `langserver/execute_command.go`

### SQL intelligence

- [Project services](https://github.com/kitagry/bqls/blob/main/langserver/internal/source/project.go): `langserver/internal/source/project.go`
- [SQL analysis](https://github.com/kitagry/bqls/blob/main/langserver/internal/source/file/analyze.go): `langserver/internal/source/file/analyze.go`
- [SQL parser](https://github.com/kitagry/bqls/blob/main/langserver/internal/source/bqparser/parser.go): `langserver/internal/source/bqparser/parser.go`
- [Completion engine](https://github.com/kitagry/bqls/blob/main/langserver/internal/source/completion/completion.go): `langserver/internal/source/completion/completion.go`
- [Document intelligence](https://github.com/kitagry/bqls/blob/main/langserver/internal/source/document.go): `langserver/internal/source/document.go`

### BigQuery services

- [BigQuery client](https://github.com/kitagry/bqls/blob/main/langserver/internal/bigquery/bigquery.go): `langserver/internal/bigquery/bigquery.go`

### Other components

- **SQL author**
- **BigQuery**
- **Google Sheets**

## Connections

- SQL author → VS Code extension: edits SQL
- SQL author → Server process: uses LSP client
- VS Code extension → Server process: starts server
- VS Code extension → Command UI: handles results
- Server process → LSP handler: creates handler
- LSP handler → Initialization: dispatches
- LSP handler → Document events: dispatches
- LSP handler → Completion: dispatches
- LSP handler → Diagnostics: dispatches
- LSP handler → Formatting: dispatches
- LSP handler → Hover details: dispatches
- LSP handler → Definition lookup: dispatches
- LSP handler → Workspace commands: dispatches
- LSP handler → Virtual documents: dispatches
- Completion → Project services: requests completion
- Completion → Completion engine: builds suggestions
- Diagnostics → Project services: requests analysis
- Formatting → Project services: formats document
- Hover details → Project services: requests details
- Definition lookup → Project services: resolves symbol
- Document events → Project services: updates documents
- Project services → SQL analysis: analyzes SQL
- SQL analysis → SQL parser: parses SQL
- Project services → Document intelligence: provides context
- Workspace commands → Project services: runs query
- Workspace commands → BigQuery client: lists jobs and data
- Project services → BigQuery client: fetches metadata
- BigQuery client → BigQuery: queries BigQuery
- Virtual documents → Project services: builds previews
- Workspace commands → Result export: exports rows
- Result export → Google Sheets: writes spreadsheets
- Workspace commands → Command UI: returns command results