# versenilvis/iris architecture

> Architecture diagram of the GitHub repository versenilvis/iris, 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/versenilvis/iris
- Repository: https://github.com/versenilvis/iris

## Overview

IRIS is a terminal-native shell completion tool: as a user edits a command line, it finds relevant suggestions, ranks and displays them inline, and supports selecting or accepting a suggestion. The map includes documented shell-history, alias, configuration, and AI capabilities. Source excerpts are partial, so some runtime wiring—especially history and ranking within the wrapper—is shown only where supported by the available evidence.

Main entry points: [`root/wrapper.go`](https://github.com/versenilvis/iris/blob/main/root/wrapper.go) (Shell wrapper), [`spec/lookup.go`](https://github.com/versenilvis/iris/blob/main/spec/lookup.go) (Completion lookup), [`internal/ai/engine.go`](https://github.com/versenilvis/iris/blob/main/internal/ai/engine.go) (AI engine), [`cmd/iris/main.go`](https://github.com/versenilvis/iris/blob/main/cmd/iris/main.go) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Shell runtime"]
  node_main["CLI entry<br/>[main.go]"]
  node_root["Command root<br/>[root.go]"]
  node_wrapper["Shell wrapper<br/>[wrapper.go]"]
  node_adapter["Shell adapter<br/>[adapter.go]"]
  node_overlay["Inline overlay<br/>[overlay.go]"]
  node_history["History integration<br/>[history.go]"]
end

subgraph group_suggest["Suggestion engine"]
  node_registry["Command registry<br/>[all.go]"]
  node_command_specs["Tool specifications"]
  node_lookup["Completion lookup<br/>[lookup.go]"]
  node_generators["Argument generators<br/>[filegen.go]"]
  node_scoring["Suggestion scoring<br/>[scorer.go]"]
end

subgraph group_context["Context and settings"]
  node_workspace["Workspace detection<br/>[workspace.go]"]
  node_config["Live configuration<br/>[config.go]"]
  node_state[("Local state<br/>[state.go]")]
end

subgraph group_ai["AI suggestions"]
  node_ai_engine["AI engine<br/>[engine.go]"]
  node_ai_context["AI context providers"]
  node_ai_client["AI API client<br/>[client.go]"]
end

node_user(("Shell user"))
node_ai_service(("AI provider"))

node_user -->|"starts"| node_main
node_main -->|"executes"| node_root
node_root -->|"runs shell"| node_wrapper
node_wrapper -->|"gets shell"| node_adapter
node_wrapper -->|"renders"| node_overlay
node_wrapper -->|"reads settings"| node_config
node_wrapper -->|"loads mode"| node_state
node_wrapper -->|"records command"| node_history
node_registry -->|"registers"| node_command_specs
node_wrapper -->|"requests matches"| node_lookup
node_lookup -->|"queries specs"| node_registry
node_lookup -->|"generates arguments"| node_generators
node_lookup -->|"ranks candidates"| node_scoring
node_scoring -->|"checks context"| node_workspace
node_wrapper -.->|"requests AI"| node_ai_engine
node_ai_engine -.->|"gathers context"| node_ai_context
node_ai_engine -.->|"requests completion"| node_ai_client
node_ai_client -.->|"sends request"| node_ai_service

click node_main "https://github.com/versenilvis/iris/blob/main/cmd/iris/main.go"
click node_root "https://github.com/versenilvis/iris/blob/main/root/root.go"
click node_wrapper "https://github.com/versenilvis/iris/blob/main/root/wrapper.go"
click node_adapter "https://github.com/versenilvis/iris/blob/main/integration/shell/adapter.go"
click node_overlay "https://github.com/versenilvis/iris/blob/main/integration/overlay.go"
click node_history "https://github.com/versenilvis/iris/blob/main/integration/history.go"
click node_registry "https://github.com/versenilvis/iris/blob/main/commands/all.go"
click node_command_specs "https://github.com/versenilvis/iris/tree/main/commands"
click node_lookup "https://github.com/versenilvis/iris/blob/main/spec/lookup.go"
click node_generators "https://github.com/versenilvis/iris/blob/main/spec/filegen.go"
click node_scoring "https://github.com/versenilvis/iris/blob/main/internal/scoring/scorer.go"
click node_workspace "https://github.com/versenilvis/iris/blob/main/internal/workspace/workspace.go"
click node_config "https://github.com/versenilvis/iris/blob/main/internal/config/config.go"
click node_state "https://github.com/versenilvis/iris/blob/main/internal/config/state.go"
click node_ai_engine "https://github.com/versenilvis/iris/blob/main/internal/ai/engine.go"
click node_ai_context "https://github.com/versenilvis/iris/blob/main/internal/ai/context_provider.go"
click node_ai_client "https://github.com/versenilvis/iris/blob/main/internal/ai/client.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_main,node_root,node_wrapper,node_adapter,node_overlay,node_history,node_user toneBlue
class node_registry,node_command_specs,node_lookup,node_generators,node_scoring toneAmber
class node_workspace,node_config,node_state toneMint
class node_ai_engine,node_ai_context,node_ai_client toneRose
class node_ai_service toneIndigo
```

## Components

### Shell runtime

- [CLI entry](https://github.com/versenilvis/iris/blob/main/cmd/iris/main.go): `cmd/iris/main.go`
- [Command root](https://github.com/versenilvis/iris/blob/main/root/root.go): `root/root.go`
- [Shell wrapper](https://github.com/versenilvis/iris/blob/main/root/wrapper.go): `root/wrapper.go`
- [Shell adapter](https://github.com/versenilvis/iris/blob/main/integration/shell/adapter.go): `integration/shell/adapter.go`
- [Inline overlay](https://github.com/versenilvis/iris/blob/main/integration/overlay.go): `integration/overlay.go`
- [History integration](https://github.com/versenilvis/iris/blob/main/integration/history.go): `integration/history.go`

### Suggestion engine

- [Command registry](https://github.com/versenilvis/iris/blob/main/commands/all.go): `commands/all.go`
- [Tool specifications](https://github.com/versenilvis/iris/tree/main/commands): `commands`
- [Completion lookup](https://github.com/versenilvis/iris/blob/main/spec/lookup.go): `spec/lookup.go`
- [Argument generators](https://github.com/versenilvis/iris/blob/main/spec/filegen.go): `spec/filegen.go`
- [Suggestion scoring](https://github.com/versenilvis/iris/blob/main/internal/scoring/scorer.go): `internal/scoring/scorer.go`

### Context and settings

- [Workspace detection](https://github.com/versenilvis/iris/blob/main/internal/workspace/workspace.go): `internal/workspace/workspace.go`
- [Live configuration](https://github.com/versenilvis/iris/blob/main/internal/config/config.go): `internal/config/config.go`
- [Local state](https://github.com/versenilvis/iris/blob/main/internal/config/state.go): `internal/config/state.go`

### AI suggestions

- [AI engine](https://github.com/versenilvis/iris/blob/main/internal/ai/engine.go): `internal/ai/engine.go`
- [AI context providers](https://github.com/versenilvis/iris/blob/main/internal/ai/context_provider.go): `internal/ai/context_provider.go`
- [AI API client](https://github.com/versenilvis/iris/blob/main/internal/ai/client.go): `internal/ai/client.go`

### Other components

- **Shell user**
- **AI provider**

## Connections

- Shell user → CLI entry: starts
- CLI entry → Command root: executes
- Command root → Shell wrapper: runs shell
- Shell wrapper → Shell adapter: gets shell
- Shell wrapper → Inline overlay: renders
- Shell wrapper → Live configuration: reads settings
- Shell wrapper → Local state: loads mode
- Shell wrapper → History integration: records command
- Command registry → Tool specifications: registers
- Shell wrapper → Completion lookup: requests matches
- Completion lookup → Command registry: queries specs
- Completion lookup → Argument generators: generates arguments
- Completion lookup → Suggestion scoring: ranks candidates
- Suggestion scoring → Workspace detection: checks context
- Shell wrapper → AI engine: requests AI
- AI engine → AI context providers: gathers context
- AI engine → AI API client: requests completion
- AI API client → AI provider: sends request