# Source code structure

This document provides a high‑level map of the Hexai source layout and how the
main packages relate to each other.

## Diagram

```mermaid
graph TD
  %% Entrypoints
  A[cmd/hexai\nCLI entrypoint] --> B[internal/hexaicli\nCLI runner]
  C[cmd/hexai-lsp\nLSP entrypoint] --> D[internal/hexailsp\nLSP runner]

  %% Shared/internal packages
  subgraph internal/
    I[appconfig\nLoad config from file/env]
    L[llm\nClient + providers]
    G[logging\nBound logger + helpers]
    S[lsp\nJSON-RPC, server, handlers]
  end

  %% Relationships
  B --> I
  B --> L
  B --> G

  D --> I
  D --> L
  D --> G
  D --> S

  S --> L
  S --> G

  %% LLM providers
  subgraph internal/llm
    P1[openai.go]
    P2[ollama.go]
    P3[copilot.go]
  end
  L --> P1
  L --> P2
  L --> P3

  %% Version info
  V[internal/version.go\nVersion string] --> A
  V --> C
```

## Module overview

- cmd/hexai: CLI binary that parses flags, prints version via `internal.Version`,
  and delegates to `internal/hexaicli.Run`.
- cmd/hexai-lsp: LSP server binary that parses flags, prints version, and calls
  `internal/hexailsp.Run` (stdio JSON‑RPC server).
- internal/hexaicli: CLI flow — reads stdin/args, loads config, builds an LLM
  client, constructs messages, and runs a single chat request (streaming when
  supported).
- internal/hexailsp: LSP orchestration — binds logging, loads config, builds the
  LLM client, constructs `internal/lsp.ServerOptions`, and runs the server.
- internal/lsp: Minimal LSP over stdio — document store, JSON‑RPC handlers
  (initialize, completion, code action, etc.), context building, and a small
  completion cache.
- internal/llm: Provider‑agnostic client interface plus concrete providers for
  OpenAI, GitHub Copilot, and Ollama, including streaming support where
  available.
- internal/appconfig: Loads user configuration from file and environment, shared
  by both CLI and LSP paths.
- internal/logging: Central logger binding and small helpers for consistent,
  readable logs and chat summaries.
- internal/version.go: Single place for the version string used by both
  binaries.

## Typical flows

- CLI: `cmd/hexai` → `internal/hexaicli` → `internal/appconfig` → `internal/llm`
  (providers) → print output and a short summary line.
- LSP: `cmd/hexai-lsp` → `internal/hexailsp` → `internal/lsp.Server` →
  request handlers → `internal/llm` for completions/actions.