# karosown/katool-go architecture

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

- Interactive diagram: https://gitdiagram.com/karosown/katool-go
- Repository: https://github.com/karosown/katool-go

## Overview

Katool-Go is a modular Go utility library, not a single end-user application. Developers call individual packages to process collections, manage state and concurrency, integrate services, or perform domain-specific tasks. The README highlights stream and collection operations, conversion, dependency injection, crawling, files, databases, networking, logging, algorithms, text tools, rules, and general utilities; the tree supports those as separate capabilities rather than one shared runtime pipeline. AI and messaging are additional substantial subsystems visible in the tree. Sampled code confirms AI tool dispatch, rule-chain execution, and crawler configuration; connections between other packages are intentionally omitted where wiring was not evidenced.

Main entry points: [`ai/agent/client.go`](https://github.com/karosown/katool-go/blob/main/ai/agent/client.go) (Agent tools), [`web_crawler/client.go`](https://github.com/karosown/katool-go/blob/main/web_crawler/client.go) (Crawler client), [`ruleengine/engine.go`](https://github.com/karosown/katool-go/blob/main/ruleengine/engine.go) (Rule engine), [`ai/client.go`](https://github.com/karosown/katool-go/blob/main/ai/client.go) (AI client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ai["AI integrations"]
  node_ai_client["AI client<br/>[client.go]"]
  node_ai_providers["AI providers"]
  node_ai_agent["Agent tools<br/>[client.go]"]
  node_mcp["MCP adapters"]
end

subgraph group_data["Data and runtime"]
  node_collections["Collections"]
  node_optionals["Optional values"]
  node_streams["Stream processing"]
  node_ioc["Dependency injection<br/>[ioc.go]"]
  node_concurrency["Concurrency control<br/>[lock.go]"]
end

subgraph group_web["Web and files"]
  node_crawler["Crawler client<br/>[client.go]"]
  node_crawler_extract["Content extraction"]
  node_file_ops["File operations"]
  node_http["HTTP clients"]
end

subgraph group_messaging["Persistence and messaging"]
  node_mongo["MongoDB tools"]
  node_redis["Redis client<br/>[client.go]"]
  node_mq["Message queues<br/>[client.go]"]
end

subgraph group_processing["Processing and utilities"]
  node_conversion["Data conversion"]
  node_rules["Rule engine<br/>[engine.go]"]
  node_algorithms["Algorithms"]
  node_text["Text processing"]
  node_utilities["Utility packages"]
  node_logging["Logging<br/>[logger.go]"]
end

node_developer(("Go developer"))
node_external_ai(("AI services"))
node_chrome(("Chrome browser"))
node_mongo_service[("MongoDB")]
node_redis_service[("Redis")]
node_queue_service(("Queue brokers"))

node_developer -->|"uses tools"| node_ai_agent
node_ai_agent -->|"sends requests"| node_ai_client
node_ai_agent -->|"dispatches tools"| node_mcp
node_ai_client -->|"selects provider"| node_ai_providers
node_ai_providers -->|"calls model"| node_external_ai
node_developer -->|"processes collections"| node_streams
node_developer -->|"uses containers"| node_collections
node_developer -->|"handles optional values"| node_optionals
node_developer -->|"registers components"| node_ioc
node_developer -->|"coordinates goroutines"| node_concurrency
node_developer -->|"converts data"| node_conversion
node_developer -->|"executes chains"| node_rules
node_rules -->|"runs chains"| node_rules
node_developer -->|"uses algorithms"| node_algorithms
node_developer -->|"analyzes text"| node_text
node_developer -->|"uses helpers"| node_utilities
node_developer -->|"crawls pages"| node_crawler
node_crawler -.->|"uses browser"| node_chrome
node_crawler -->|"extracts content"| node_crawler_extract
node_developer -->|"handles files"| node_file_ops
node_developer -->|"sends requests"| node_http
node_developer -->|"queries data"| node_mongo
node_mongo -->|"reads and writes"| node_mongo_service
node_developer -->|"accesses cache"| node_redis
node_redis -->|"reads and writes"| node_redis_service
node_developer -->|"publishes and subscribes"| node_mq
node_mq -->|"exchanges messages"| node_queue_service
node_developer -->|"records events"| node_logging

click node_ai_client "https://github.com/karosown/katool-go/blob/main/ai/client.go"
click node_ai_providers "https://github.com/karosown/katool-go/tree/main/ai/providers"
click node_ai_agent "https://github.com/karosown/katool-go/blob/main/ai/agent/client.go"
click node_mcp "https://github.com/karosown/katool-go/tree/main/ai/agent"
click node_collections "https://github.com/karosown/katool-go/tree/main/container/xmap"
click node_optionals "https://github.com/karosown/katool-go/tree/main/container/optional"
click node_streams "https://github.com/karosown/katool-go/tree/main/container/stream"
click node_ioc "https://github.com/karosown/katool-go/blob/main/container/ioc/ioc.go"
click node_concurrency "https://github.com/karosown/katool-go/blob/main/lock/lock.go"
click node_conversion "https://github.com/karosown/katool-go/tree/main/convert"
click node_rules "https://github.com/karosown/katool-go/blob/main/ruleengine/engine.go"
click node_algorithms "https://github.com/karosown/katool-go/tree/main/algorithm"
click node_text "https://github.com/karosown/katool-go/tree/main/words"
click node_utilities "https://github.com/karosown/katool-go/tree/main/util"
click node_crawler "https://github.com/karosown/katool-go/blob/main/web_crawler/client.go"
click node_crawler_extract "https://github.com/karosown/katool-go/tree/main/web_crawler"
click node_file_ops "https://github.com/karosown/katool-go/tree/main/file"
click node_http "https://github.com/karosown/katool-go/tree/main/net/http"
click node_mongo "https://github.com/karosown/katool-go/tree/main/db/xmongo"
click node_redis "https://github.com/karosown/katool-go/blob/main/db/xredis/client.go"
click node_mq "https://github.com/karosown/katool-go/blob/main/mq/client.go"
click node_logging "https://github.com/karosown/katool-go/blob/main/xlog/logger.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_ai_client,node_ai_providers,node_ai_agent,node_mcp,node_chrome toneBlue
class node_collections,node_optionals,node_streams,node_ioc,node_concurrency,node_mongo_service,node_redis_service toneAmber
class node_crawler,node_crawler_extract,node_file_ops,node_http toneMint
class node_mongo,node_redis,node_mq,node_queue_service toneRose
class node_conversion,node_rules,node_algorithms,node_text,node_utilities,node_logging,node_developer,node_external_ai toneIndigo
```

## Components

### AI integrations

- [AI client](https://github.com/karosown/katool-go/blob/main/ai/client.go): `ai/client.go`
- [AI providers](https://github.com/karosown/katool-go/tree/main/ai/providers): `ai/providers`
- [Agent tools](https://github.com/karosown/katool-go/blob/main/ai/agent/client.go): `ai/agent/client.go`
- [MCP adapters](https://github.com/karosown/katool-go/tree/main/ai/agent): `ai/agent`

### Data and runtime

- [Collections](https://github.com/karosown/katool-go/tree/main/container/xmap): `container/xmap`
- [Optional values](https://github.com/karosown/katool-go/tree/main/container/optional): `container/optional`
- [Stream processing](https://github.com/karosown/katool-go/tree/main/container/stream): `container/stream`
- [Dependency injection](https://github.com/karosown/katool-go/blob/main/container/ioc/ioc.go): `container/ioc/ioc.go`
- [Concurrency control](https://github.com/karosown/katool-go/blob/main/lock/lock.go): `lock/lock.go`

### Web and files

- [Crawler client](https://github.com/karosown/katool-go/blob/main/web_crawler/client.go): `web_crawler/client.go`
- [Content extraction](https://github.com/karosown/katool-go/tree/main/web_crawler): `web_crawler`
- [File operations](https://github.com/karosown/katool-go/tree/main/file): `file`
- [HTTP clients](https://github.com/karosown/katool-go/tree/main/net/http): `net/http`

### Persistence and messaging

- [MongoDB tools](https://github.com/karosown/katool-go/tree/main/db/xmongo): `db/xmongo`
- [Redis client](https://github.com/karosown/katool-go/blob/main/db/xredis/client.go): `db/xredis/client.go`
- [Message queues](https://github.com/karosown/katool-go/blob/main/mq/client.go): `mq/client.go`

### Processing and utilities

- [Data conversion](https://github.com/karosown/katool-go/tree/main/convert): `convert`
- [Rule engine](https://github.com/karosown/katool-go/blob/main/ruleengine/engine.go): `ruleengine/engine.go`
- [Algorithms](https://github.com/karosown/katool-go/tree/main/algorithm): `algorithm`
- [Text processing](https://github.com/karosown/katool-go/tree/main/words): `words`
- [Utility packages](https://github.com/karosown/katool-go/tree/main/util): `util`
- [Logging](https://github.com/karosown/katool-go/blob/main/xlog/logger.go): `xlog/logger.go`

### Other components

- **Go developer**
- **AI services**
- **Chrome browser**
- **MongoDB**
- **Redis**
- **Queue brokers**

## Connections

- Go developer → Agent tools: uses tools
- Agent tools → AI client: sends requests
- Agent tools → MCP adapters: dispatches tools
- AI client → AI providers: selects provider
- AI providers → AI services: calls model
- Go developer → Stream processing: processes collections
- Go developer → Collections: uses containers
- Go developer → Optional values: handles optional values
- Go developer → Dependency injection: registers components
- Go developer → Concurrency control: coordinates goroutines
- Go developer → Data conversion: converts data
- Go developer → Rule engine: executes chains
- Rule engine → Rule engine: runs chains
- Go developer → Algorithms: uses algorithms
- Go developer → Text processing: analyzes text
- Go developer → Utility packages: uses helpers
- Go developer → Crawler client: crawls pages
- Crawler client → Chrome browser: uses browser
- Crawler client → Content extraction: extracts content
- Go developer → File operations: handles files
- Go developer → HTTP clients: sends requests
- Go developer → MongoDB tools: queries data
- MongoDB tools → MongoDB: reads and writes
- Go developer → Redis client: accesses cache
- Redis client → Redis: reads and writes
- Go developer → Message queues: publishes and subscribes
- Message queues → Queue brokers: exchanges messages
- Go developer → Logging: records events