From 69fb353b042ebc0e288bc60ccc1c4f7403994d13 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 31 Aug 2025 23:50:32 +0300
Subject: update the status

---
 docs/source-structure.md | 127 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 docs/source-structure.md

(limited to 'docs/source-structure.md')

diff --git a/docs/source-structure.md b/docs/source-structure.md
new file mode 100644
index 0000000..65db4d9
--- /dev/null
+++ b/docs/source-structure.md
@@ -0,0 +1,127 @@
+# 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
+```
+
+## ASCII diagram
+
+```
+                          +----------------------+
+                          | internal/version.go  |
+                          +----------------------+
+                               |  provides Version
+                 +-------------+-------------+
+                 |                           |
+          +--------------+            +----------------+
+          | cmd/hexai    |            | cmd/hexai-lsp  |
+          | (CLI)        |            | (LSP server)   |
+          +--------------+            +----------------+
+                 |                           |
+                 v                           v
+        +------------------+          +------------------+
+        | internal/hexaicli|          | internal/hexailsp|
+        | (CLI runner)     |          | (LSP runner)     |
+        +------------------+          +------------------+
+            |    |    |                     |   |   |
+            |    |    |                     |   |   +----> logging
+            |    |    +----> logging        |   +--------> llm (client)
+            |    +--------> llm (client)    +-------------> appconfig
+            +-------------> appconfig                    |
+                                                       builds options
+                                                           v
+                                                    +------------------+
+                                                    | internal/lsp     |
+                                                    | (server, JSON-RPC|
+                                                    |  handlers, docs) |
+                                                    +------------------+
+                                                         |        |
+                                                         |        +----> logging
+                                                         +-------------> llm (client)
+
+  llm providers:
+    +-----------------------------+
+    | internal/llm/providers      |
+    |  - openai.go                |
+    |  - ollama.go                |
+    |  - copilot.go               |
+    +-----------------------------+
+
+  shared libs:
+    - internal/appconfig: config from file/env
+    - internal/logging: logger binding + helpers
+```
+
+## 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.
-- 
cgit v1.2.3