# abhiraj-ku/icli architecture

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

- Interactive diagram: https://gitdiagram.com/abhiraj-ku/icli
- Repository: https://github.com/abhiraj-ku/icli

## Overview

iCli is a read-only PostgreSQL advisor CLI. Its main command connects to PostgreSQL, selects expensive statements, explains and analyzes their plans, then reports unused indexes and missing foreign-key indexes; a separate `report` command collects health metrics. The README documents all major capabilities, while sampled source confirms the main analysis, reporting, and health paths. The update command is documented in source but is separate from database analysis.

Main entry points: [`cmd/icli/main.go`](https://github.com/abhiraj-ku/icli/blob/main/cmd/icli/main.go) (Command routing), [`internals/health/collector.go`](https://github.com/abhiraj-ku/icli/blob/main/internals/health/collector.go) (Health metrics collection), [`internals/db/connect.go`](https://github.com/abhiraj-ku/icli/blob/main/internals/db/connect.go) (DB connection pool), [`internals/db/stats.go`](https://github.com/abhiraj-ku/icli/blob/main/internals/db/stats.go) (Expensive query stats)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI orchestration"]
  node_entry["Command routing<br/>[main.go]"]
end

subgraph group_analysis["Query and index analysis"]
  node_connection["DB connection pool<br/>[connect.go]"]
  node_query_stats["Expensive query stats<br/>[stats.go]"]
  node_explain["Plan retrieval<br/>[explain.go]"]
  node_plan_analysis["Plan traversal<br/>[engine.go]"]
  node_plan_rules["Bottleneck rules<br/>[rules.go]"]
  node_unused_indexes["Unused index scan<br/>[stats.go]"]
  node_missing_fk["Missing FK index scan<br/>[stats.go]"]
end

subgraph group_health["Health reporting"]
  node_health_collect["Health metrics collection<br/>[collector.go]"]
  node_health_types["Health report data<br/>[types.go]"]
end

subgraph group_presentation["Terminal presentation"]
  node_query_print["Analysis output<br/>[printer.go]"]
  node_health_print["Health output<br/>[health.go]"]
end

node_user(("CLI user"))
node_postgres[("PostgreSQL")]
node_terminal(("Terminal"))
node_update_service["Release update service"]

node_user -->|"runs command"| node_entry
node_entry -->|"opens pool"| node_connection
node_connection -->|"connects"| node_postgres
node_entry -->|"fetches top queries"| node_query_stats
node_query_stats -->|"reads statistics"| node_postgres
node_entry -->|"requests plans"| node_explain
node_explain -->|"runs EXPLAIN"| node_postgres
node_entry -->|"analyzes plans"| node_plan_analysis
node_plan_analysis -->|"evaluates nodes"| node_plan_rules
node_entry -->|"fetches unused indexes"| node_unused_indexes
node_unused_indexes -->|"reads index stats"| node_postgres
node_entry -->|"fetches missing indexes"| node_missing_fk
node_missing_fk -->|"reads catalog"| node_postgres
node_entry -->|"prints findings"| node_query_print
node_query_print -->|"renders output"| node_terminal
node_entry -->|"fetches health report"| node_health_collect
node_health_collect -->|"reads health metrics"| node_postgres
node_health_collect -->|"populates report"| node_health_types
node_entry -->|"renders report"| node_health_print
node_health_print -->|"prints report"| node_terminal
node_user -.->|"requests update"| node_update_service

click node_entry "https://github.com/abhiraj-ku/icli/blob/main/cmd/icli/main.go"
click node_connection "https://github.com/abhiraj-ku/icli/blob/main/internals/db/connect.go"
click node_query_stats "https://github.com/abhiraj-ku/icli/blob/main/internals/db/stats.go"
click node_explain "https://github.com/abhiraj-ku/icli/blob/main/internals/db/explain.go"
click node_plan_analysis "https://github.com/abhiraj-ku/icli/blob/main/internals/analyzer/engine.go"
click node_plan_rules "https://github.com/abhiraj-ku/icli/blob/main/internals/analyzer/rules.go"
click node_unused_indexes "https://github.com/abhiraj-ku/icli/blob/main/internals/db/stats.go"
click node_missing_fk "https://github.com/abhiraj-ku/icli/blob/main/internals/db/stats.go"
click node_health_collect "https://github.com/abhiraj-ku/icli/blob/main/internals/health/collector.go"
click node_health_types "https://github.com/abhiraj-ku/icli/blob/main/internals/health/types.go"
click node_query_print "https://github.com/abhiraj-ku/icli/blob/main/internals/report/printer.go"
click node_health_print "https://github.com/abhiraj-ku/icli/blob/main/internals/report/health.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_entry,node_user toneBlue
class node_connection,node_query_stats,node_explain,node_plan_analysis,node_plan_rules,node_unused_indexes,node_missing_fk,node_postgres toneAmber
class node_health_collect,node_health_types toneMint
class node_query_print,node_health_print toneRose
class node_terminal,node_update_service toneIndigo
```

## Components

### CLI orchestration

- [Command routing](https://github.com/abhiraj-ku/icli/blob/main/cmd/icli/main.go): `cmd/icli/main.go`

### Query and index analysis

- [DB connection pool](https://github.com/abhiraj-ku/icli/blob/main/internals/db/connect.go): `internals/db/connect.go`
- [Expensive query stats](https://github.com/abhiraj-ku/icli/blob/main/internals/db/stats.go): `internals/db/stats.go`
- [Plan retrieval](https://github.com/abhiraj-ku/icli/blob/main/internals/db/explain.go): `internals/db/explain.go`
- [Plan traversal](https://github.com/abhiraj-ku/icli/blob/main/internals/analyzer/engine.go): `internals/analyzer/engine.go`
- [Bottleneck rules](https://github.com/abhiraj-ku/icli/blob/main/internals/analyzer/rules.go): `internals/analyzer/rules.go`
- [Unused index scan](https://github.com/abhiraj-ku/icli/blob/main/internals/db/stats.go): `internals/db/stats.go`
- [Missing FK index scan](https://github.com/abhiraj-ku/icli/blob/main/internals/db/stats.go): `internals/db/stats.go`

### Health reporting

- [Health metrics collection](https://github.com/abhiraj-ku/icli/blob/main/internals/health/collector.go): `internals/health/collector.go`
- [Health report data](https://github.com/abhiraj-ku/icli/blob/main/internals/health/types.go): `internals/health/types.go`

### Terminal presentation

- [Analysis output](https://github.com/abhiraj-ku/icli/blob/main/internals/report/printer.go): `internals/report/printer.go`
- [Health output](https://github.com/abhiraj-ku/icli/blob/main/internals/report/health.go): `internals/report/health.go`

### Other components

- **CLI user**
- **PostgreSQL**
- **Terminal**
- **Release update service**

## Connections

- CLI user → Command routing: runs command
- Command routing → DB connection pool: opens pool
- DB connection pool → PostgreSQL: connects
- Command routing → Expensive query stats: fetches top queries
- Expensive query stats → PostgreSQL: reads statistics
- Command routing → Plan retrieval: requests plans
- Plan retrieval → PostgreSQL: runs EXPLAIN
- Command routing → Plan traversal: analyzes plans
- Plan traversal → Bottleneck rules: evaluates nodes
- Command routing → Unused index scan: fetches unused indexes
- Unused index scan → PostgreSQL: reads index stats
- Command routing → Missing FK index scan: fetches missing indexes
- Missing FK index scan → PostgreSQL: reads catalog
- Command routing → Analysis output: prints findings
- Analysis output → Terminal: renders output
- Command routing → Health metrics collection: fetches health report
- Health metrics collection → PostgreSQL: reads health metrics
- Health metrics collection → Health report data: populates report
- Command routing → Health output: renders report
- Health output → Terminal: prints report
- CLI user → Release update service: requests update
