# s19835/pg-opt-toolkit architecture

> Architecture diagram of the GitHub repository s19835/pg-opt-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/s19835/pg-opt-toolkit
- Repository: https://github.com/s19835/pg-opt-toolkit

## Overview

##### Project type and purpose
- This is a Go-based CLI tool (“PostgreSQL Query Optimizer Toolkit”) for running `EXPLAIN ANALYZE`, parsing the resulting JSON plan, and highlighting basic bottlenecks in PostgreSQL queries.

##### File structure
- cmd/pgopt: entry point (CLI using cobra)
- internal/config: reads YAML/env via Viper
- internal/connector: opens and manages pgx database connections
- internal/analyzer: core logic that examines parsed plans and flags slow operations
- pkg/queryplan: JSON plan parser, builds intermediate representations
- pkg/models: Go structs modeling plan nodes and analysis results
- go.mod/go.sum: module and dependency management

##### README for additional insights
- Uses cobra for CLI, viper for configuration, pgx for DB driver
- Workflow: user runs `pgopt analyze "<SQL>"` → connect to Postgres → run EXPLAIN ANALYZE → parse/ analyze → print human-readable output

a. Main components
- CLI Layer (cmd/pgopt)
- Configuration Layer (internal/config + Viper)
- Connector Layer (internal/connector + pgx)
- QueryPlan Parser (pkg/queryplan)
- Domain Models (pkg/models)
- Analyzer Engine (internal/analyzer)
- External System: PostgreSQL Database
- End-User/Terminal

b. Relationships & interactions
1. User invokes CLI command →
2. CLI Layer loads configuration from files/env →
3. Connector Layer establishes connection to Postgres →
4. Connector Layer issues `EXPLAIN ANALYZE` →
5. JSON plan is returned →
6. QueryPlan Parser deserializes JSON into domain models →
7. Analyzer Engine processes models to detect bottlenecks →
8. CLI Layer formats and outputs analysis to terminal

c. Architectural patterns & design principles
- Layered architecture (presentation → config → connector → domain → analysis)
- Clear separation of concerns (CLI vs. config vs. data access vs. business logic)
- Internal vs. pkg distinction: internal packages are non-public, pkg is reusable

d. Key technologies & libraries
- Go 1.18+
- cobra (CLI)
- viper (config)
- pgx/v5 (PostgreSQL driver)
- encoding/json (built-in JSON parsing)

## Diagram (Mermaid)

```mermaid
flowchart TB
    terminal["Terminal"]:::cli
    cli["CLI Layer"]:::cli
    subgraph "Internal Modules"
        config["Configuration Layer"]:::internal
        connector["Connector Layer"]:::internal
        analyzer["Analyzer Engine"]:::internal
    end
    subgraph "Pkg Modules"
        parser["QueryPlan Parser"]:::pkg
        models["Domain Models"]:::pkg
    end
    db[(PostgreSQL Database)]:::external

    terminal -->|"1: invoke CLI command"| cli
    cli -->|"2: load configuration"| config
    config -->|"3: establish DB connection"| connector
    connector -->|"4: EXPLAIN ANALYZE"| db
    db -->|"5: return JSON plan"| connector
    connector -->|"6: pass JSON"| parser
    parser -->|"7: map to structs"| models
    models -->|"8: analyze plan"| analyzer
    analyzer -->|"9: format results"| cli
    cli -->|"10: output to terminal"| terminal

    click cli "https://github.com/s19835/pg-opt-toolkit/blob/main/cmd/pgopt/main.go"
    click config "https://github.com/s19835/pg-opt-toolkit/blob/main/internal/config/config.go"
    click connector "https://github.com/s19835/pg-opt-toolkit/blob/main/internal/connector/pg_connector.go"
    click parser "https://github.com/s19835/pg-opt-toolkit/blob/main/pkg/queryplan/parser.go"
    click models "https://github.com/s19835/pg-opt-toolkit/blob/main/pkg/models/datamodel.go"
    click analyzer "https://github.com/s19835/pg-opt-toolkit/blob/main/internal/analyzer/analyzer.go"

    classDef cli fill:#cccccc,stroke:#333,stroke-width:2px
    classDef internal fill:#aecbfa,stroke:#1f77b4,stroke-width:2px
    classDef pkg fill:#c7e9c0,stroke:#2ca02c,stroke-width:2px
    classDef external fill:#ffcc99,stroke:#d62728,stroke-width:2px
```
